Quick Start

Get up and running! ๐Ÿ‘Ÿ๐Ÿ‘Ÿ

Let's get you started! This guide will walk you through the most important steps

Install the SDK ๐Ÿ”ง

Our iOS SDK is distributed as as a SPM package (Swift Package Manager). Simply add a SPM dependency in Xcode on https://github.com/criticalmoments/criticalmoments.

Detailed Steps
  • Open your app project in Xcode. Click "File" > "Add Package Dependencies..."

  • Paste the following URL in the search box in the top right: https://github.com/criticalmoments/criticalmoments and select the Critical Moments package. We suggest leaving the default settings for dependency rules: (Branch=main). We only merge stable releases to our main branch.

  • Select the correct project in the "Add to Project..." dropdown if not already selected

  • Click "Add Package"

Create an API Key ๐Ÿ”‘

The API key is only valid for the app with the bundle ID you provide during setup.

Create your config file ๐Ÿ“„

Create a JSON config file to your XCode project, starting with a template:

  • Create a copy of of the file cmDevConfig.json template file below, replacing YOUR_BUNDLE_ID with your real bundle ID. This template includes a simple launch message which will help your verify the integration is working.

  • Add the file to your Xcode project. Ensure you check the "Target Membership" box for your app.

  • In Xcode open "Project Settings" > "Build Phases" > "Copy Bundle Resources", and verify the file you just added to the project is listed. If not, add it!

cmDevConfig.json Template
    "configVersion": "v1",
    "appId": "YOUR_BUNDLE_ID",
    "triggers": {
        "namedTriggers": {
            "launchMessageTrigger": {
                "eventName": "app_start",
                "actionName": "launchAlert"
    "actions": {
        "namedActions": {
            "launchAlert": {
                "actionType": "conditional_action",
                "actionData": {
                    "condition": "interface_orientation == 'landscape'",
                    "passedActionName": "landscapeAlert",
                    "failedActionName": "portraitAlert"
            "landscapeAlert": {
                "actionType": "alert",
                "actionData": {
                    "title": "Launched Landscape",
                    "message": "The app was launched while in landscape orientation."
            "portraitAlert": {
                "actionType": "alert",
                "actionData": {
                    "title": "Launched Portrait",
                    "message": "The app was launched while in portrait orientation."

Integrate the SDK into your app ๐Ÿงฉ

Add the following code snippet into your app.

  • Put it somewhere that will run right after app startup, such as AppDelegate.didFinishLaunchingWithOptions

  • Replace the YOUR_API_KEY string with your real API key

  • The console will show a warning for now, but this will be resolved in a later step of this guide

In your App Delegate imports add:

import CriticalMoments

In App Delegate's application(_:didFinishLaunchingWithOptions:) add:

CriticalMoments.sharedInstance().setApiKey("YOUR_API_KEY", error: nil)
let localConfigUrl = Bundle.main.url(forResource: "cmDevConfig", withExtension: "json")!

Startup work will be dispatched to background threads, and will not impact your app's startup time.

Test the integration ๐Ÿงช

Launch your app! If the integration is working, you should get an alert after startup driven by the template config file. It will tell you if your app was launched in landscape or portrait, and rotating your device/simulator then re-launching should give the opposite result.

The more Critical Moments knows about your user's behaviours, the better you can target and optimize with Critical Moments.

We recommend you log important events, including the important actions your users performs in app. See the events documentation for the suggested events and details.


Properties are datapoints used in targeting. The more useful data you add, the more powerful the targeting system can be.

We recommend you add the important properties like account_creation_date, has_subscription, and others. See the custom properties documentation for suggested custom properties, and API reference.

CriticalMoments.sharedInstance().registerIntegerProperty(42, forKey: "max_game_level", error: nil)

Setup a cloud config file โ˜๏ธ

For local development you can use your local JSON config file built into the app binary. However, production builds must use a signed config file, hosted on the web.

Read the Remote Control Docs for the best practices of picking a hosting provider, signing, and deploying your config.

Once deployed, set the release config URL using this code snippet in your App Delegate:

// Add this before `CriticalMoments.sharedInstance().start()`

Update Anytime

Deploying the config file can be done outside of app releases, allowing you to update your apps behaviour without waiting for app reviews, or users to update their builds!

Start building ๐Ÿ—๏ธ

Remove the demo actions and triggers from your copy of cmDevConfig.json and start building using the powerful combination of conditionals, events, properties, feature flags, and actions!

Some good places to start and get ideas:

  • Read our Concepts Overview to understand all the tools at your disposal.

  • Try our Demo App for an interactive demo of conditionals, themes, and actions.

Last updated