Get Started for iOS

To build your Flutter mobile application with iOS as your primary development target with the Flutter SDK, you will need to set up the environment required for developing an iOS app in Catalyst.

Prerequisites and Minimum Supported Environments

Before you begin working with your Flutter app on the iOS platform, you must ensure that you meet the following prerequisites and configure these minimum supported environments:

You can now register your app with Catalyst and download the configuration file that is provided tailored to your app. You must include this configuration file in your iOS app’s structure, as it will contain the definitions of certain properties required for your app to function properly.


After you create the Catalyst project and the iOS project, you must follow these steps to set up and integrate the iOS SDK package with your app.

Step 1: Register your iOS app with Catalyst

You can begin by creating a package for the iOS app in Catalyst to register it, and downloading its unique configuration file.

  1. Click the Settings icon from your Catalyst console in your project. catalyst_sdk_android_settings_icon

  2. Navigate to Developer Tools under Project Settings in the settings menu, then click on the iOS tile. ios_sdk_all_package

Alternatively, you can click the Add Package button below.

  1. Enter a package name that will identify it uniquely. Provide the URL to redirect the end-user to after they login to the app, as the Redirect URL. ios_sdk_create_package

The values that you enter here will be auto-filled in the configuration file.

Note: A package name will be uniquely associated with that OS. Therefore, you cannot create packages with the same name for both Android and iOS apps. You must provide unique values.

Ensure that iOS is selected as the OS type.

  1. Click Create to create the mobile SDK package.

  2. The console will then display a window from where you can download the configuration file. Click Download to download the file. ios_sdk_package_created

The file will be downloaded with all the required configurations. The properties in this file are explained in the next step.

Step 2: Import the Configuration File in Your iOS Project

Catalyst provides two work environments to develop and build your applications in: a Development sandbox and a live Production environment. You can learn more about them from the Environments help page.

When you create a package in the console, only the development environment’s configuration file will be available for download initially, irrespective of the environment you are working in currently. You can choose to download the configuration file from the console for any environment any time, once the package has been created.

The configuration files of each environment would be named as:

  • Development: AppConfigurationDevelopment.plist
  • Production: AppConfigurationProduction.plist

Based on the environment that you are working in, you must download and add the appropriate file to Targets -> Runner your iOS project. To obtain a production environment configuration file, you must deploy your project to production first and then download the file from the Developer Tools settings section.

The configuration file must be added to Targets -> Runner of your iOS project. catalyst_sdk_ios_properties_file

Refer to the official iOS documentation for detailed help on iOS project structure.

Properties of the AppConfigurationDevelopment.plist/ AppConfigurationProduction.plist File

The app configuration file defines the properties mentioned in the table below. All these values except the request headers are automatically populated, based on your project’s details or the default standards.

Note: You can refer to the links specified in the table, to know where you can obtain these values from.
Property Data Type Description
ClientID String Unique identifier of your app client registered in Catalyst. This is received in the configuration file.
ClientSecretID String Secret value generated for a specific clientID, which is passed along with the API hits. This is received in the configuration file.
PortalID String Unique identifier received in the configuration file
RedirectURLScheme String The callback URL of your app that you provided while creating a package for it in the console, in the previous step
ProjectID Long The unique ID of your Catalyst Project
APIBaseURL String The URL of the Catalyst server through which the internal API is called. You must use the appropriate URL (development URL or production URL), based on the environment you are working in.
APIVersion String Version of the API
OauthScopes String The scopes that would be used by the app to access the Catalyst APIs from your project. You can find the available OAuth scopes here.
RequestHeaders String The headers that would be sent by the client in the HTTP requests
The values of the request headers must be individual key-value pairs, separated by commas like: requestHeaders=key1:value1, key2:value2
ServerTLD String The top level domain of the data server
Acceptable values: AU, CN, COM, EU and IN
MinLogLevel String Enables you to set the logging preferences for the app
Acceptable values: warnings, errors, information, debug, ALL
TurnLoggerOn Boolean Turns the logger on based on the value
Acceptable values: true, false
RequestTimeOut Double The time duration (in seconds) a task must wait for additional data to arrive before giving up
JWTClientID String The client ID property of the custom server token (JSON Web Token token) generated for third-party authentication to be passed to the client
JWTClientSecret String The client secret property of the custom server token (JSON Web Token token) generated for third-party authentication to be passed to the client
  • If the values of the clientID, clientSecretID, projectID, or portalID are modified in the configuration file, it will affect the functioning of the SDK and your iOS app. If you wish to change any of these configurations, you can create a new package for the required project from the Developer Tools section and download a new configuration file for the appropriate environment, and add it to your iOS project.

  • The values of the properties that are populated in the downloaded configurations file can be dynamically accessed using the ZCatalystApp.configs object.

Step 3: Configure App Login Redirection

When a user logs in to your app successfully, they will be redirected to your app’s home screen. This user login and redirection is handled by the Catalyst SDK.

To ensure that this redirection is handled properly, include the key given below with the same configurations in the info.plist file of your iOS project:

Key - URL Types -----> URL Schemes
Type - String
Value - The Redirect URL that you configured while creating the package for your app in Catalyst


The setup for building a Flutter app with iOS as the primary development target is now ready. You can now proceed to implementing Catalyst Flutter SDK in your app.

Last Updated 2023-12-08 22:04:38 +0530 +0530