CriticalMoments

Objective-C

@interface CriticalMoments : NSObject

Swift

class CriticalMoments : NSObject

The primary interface into Critical Moments. See out getting started docs for usage instructions: https://docs.criticalmoments.io/get-started

  • Unavailable

    init is not available. Use sharedInstance for all use cases.

    Declaration

    Objective-C

    - (nonnull instancetype)init;

  • The default instance of Critical Moments. You should always use this instance.

    Declaration

    Objective-C

    + (nonnull CriticalMoments *)shared;

    Swift

    class func shared() -> CriticalMoments

Setup

  • Start should be called once you’ve performed all needed initialization for critical moments. Critical moments won’t perform actions until it is started. This is typically called in AppDelegate didfinishlaunchingwithoptions, but can be anywhere you like, as long as the primary root view controler is already rendering when you call start.

    Initializtion that should be performed before calling start:

    • Set critical moments API key (required)
    • Set critical moments config URLs (required). See setDevelopmentConfigName: and setReleaseConfigUrl:
    • Setup a default theme from code (optional). Can also be done through config. or not at all.

    Declaration

    Objective-C

    - (void)start;

    Swift

    func start()

  • Set the API Key for critical moments.

    You can get a valid API key from criticalmoments.io

    API Keys are not transferable; each app requires it’s own key.

    Declaration

    Objective-C

    - (void)setApiKey:(nonnull NSString *)apiKey
            error:(NSError *_Nullable *_Nullable)error;

    Swift

    func setApiKey(_ apiKey: String, error: NSErrorPointer)

    Parameters

    apiKey

    the API Key. Create one on criticalmoments.io
    error

    optional, any error created when validating the API key

  • Set a local development config file for Critical Moments by name. Path will be looked up in your main bundle.

    For local development you may use a local and unsigned JSON config file built into the app binary. See the Quick Start guide for how to create this file: https://docs.criticalmoments.io/quick-start

    This local config file will not be used on release builds / app store builds. You must also set a production config URL with setProductionConfigUrl for those builds.

    Declaration

    Objective-C

    - (void)setDevelopmentConfigName:(nonnull NSString *)configFileName;

    Swift

    func setDevelopmentConfigName(_ configFileName: String)

    Parameters

    configFileName

    the name of the config file (e.g. cmConfig.json). The full path will be looked up in your main bundle.

  • Set a local development config URL for Critical Moments.

    For local development you may use a local and unsigned JSON config file built into the app binary. See the Quick Start guide for how to create this file: https://docs.criticalmoments.io/quick-start

    This local config file will not be used on release builds / app store builds. You must also set a production config URL with setProductionConfigUrl for those builds.

    Declaration

    Objective-C

    - (void)setDevelopmentConfigUrl:(nonnull NSString *)urlString;

    Swift

    func setDevelopmentConfigUrl(_ urlString: String)

    Parameters

    urlString

    the URL string of the json config file. Should begin with file://

  • Set the config URL for Critical Moments to be used on release builds / app store builds

    This url should begin with https://, and should link to a signed Critical Moments configuration file. See the docs for details: https://docs.criticalmoments.io/config-file

    Warning

    Be sure to secure who can upload files to this URL path. This config file can present messages directly to your users, and you should treat security seriously, as you would your app update release process or webpage security.

    Declaration

    Objective-C

    - (void)setReleaseConfigUrl:(nonnull NSString *)urlString;

    Swift

    func setReleaseConfigUrl(_ urlString: String)

    Parameters

    urlString

    the URL string of the json config file. Should begin with https://

Events

  • Use SendEvent to sent a named events to Critical Moments (example: user_updated_profile_photo). These events may trigger actions, or may be used in conditions.

    Declaration

    Objective-C

    - (void)sendEvent:(nonnull NSString *)eventName;

    Swift

    func sendEvent(_ eventName: String)

    Parameters

    eventName

    a string describing the event. Example: user_updated_profile_photo

  • Set to true to log events and conditions to console, as they occur. Primarily uses in debugging, and should be disabled in release builds. Disabled by default.

    Declaration

    Objective-C

    - (void)setDeveloperMode:(_Bool)devMode;

    Swift

    func setDeveloperMode(_ devMode: Bool)

    Parameters

    devMode

    if true, the CM SDK will log events and conditions as they occur

Feature Flags / Named Conditions

  • Checks a named condition string, returning the result of evaluating it. The provided name is used to lookup a condition in the config file’s namedConditions section.

    Configuration documentation: https://docs.criticalmoments.io/conditional-targeting/named-conditions

    The result is returned through the provided handler asynchronously. The result is asynchronous because some conditions can use properties which are asynchronous (checking network state, battery state, and many others). It is not called on the main thread, so be sure to dispatch to the main thread if calling into UI libraries.

    Warning

    Be sure to provide a unique name to each use case. Reusing names (even if the current conditional logic is currently equivalent) will make it impossible to override each usage independently from remote configuration.

    Declaration

    Objective-C

    - (void)checkNamedCondition:(NSString *_Nonnull)name
          completionHandler:(void (^_Nonnull)(_Bool, NSError *_Nullable))result;

    Swift

    func checkNamedCondition(_ name: String) async throws -> Bool

    Parameters

    name

    The name of this condition. Must be provided and can not be an empty string. The name is used as a lookup the condition-string of a namedCondition in the config file.
    result

    Returns the boolean result of the condition evaluation. The boolean value is false for any error, including if the condition is not found in the config. Also returns/throws any errors occurred evaluating the condition.

Properties

  • Set a custom or well-known string property for use in the CM condition engine.

    Declaration

    Objective-C

    - (BOOL)setStringProperty:(nonnull NSString *)value
                   forKey:(nonnull NSString *)name
                    error:(NSError *_Nullable *_Nullable)error;

    Swift

    func setStringProperty(_ value: String, forKey name: String) throws

    Parameters

    value

    The property value
    name

    The property key/name. Can be used in conditions as “name” or “custom_name”
    error

    Any errors encountered setting the property

    Return Value

    True if call was successful. An error will be returned/thrown if false.

  • Set a custom or well-known integer (int64) property for use in the CM condition engine.

    Declaration

    Objective-C

    - (BOOL)setIntegerProperty:(long long)value
                    forKey:(nonnull NSString *)name
                     error:(NSError *_Nullable *_Nullable)error;

    Swift

    func setIntegerProperty(_ value: Int64, forKey name: String) throws

    Parameters

    value

    The property value
    name

    The property key/name. Can be used in conditions as “name” or “custom_name”
    error

    Any errors encountered setting the property

    Return Value

    True if call was successful. An error will be returned/thrown if false.

  • Set a custom or well-known boolean property for use in the CM condition engine.

    Declaration

    Objective-C

    - (BOOL)setBoolProperty:(BOOL)value
                 forKey:(nonnull NSString *)name
                  error:(NSError *_Nullable *_Nullable)error;

    Swift

    func setBoolProperty(_ value: Bool, forKey name: String) throws

    Parameters

    value

    The property value
    name

    The property key/name. Can be used in conditions as “name” or “custom_name”
    error

    Any errors encountered setting the property

    Return Value

    True if call was successful. An error will be returned/thrown if false.

  • Set a custom or well-known floating point (double) property for use in the CM condition engine.

    Declaration

    Objective-C

    - (BOOL)setFloatProperty:(double)value
                  forKey:(nonnull NSString *)name
                   error:(NSError *_Nullable *_Nullable)error;

    Swift

    func setFloatProperty(_ value: Double, forKey name: String) throws

    Parameters

    value

    The property value
    name

    The property key/name. Can be used in conditions as “name” or “custom_name”
    error

    Any errors encountered setting the property

    Return Value

    True if call was successful. An error will be returned/thrown if false.

  • Register a custom or well-known timestamp property (NSDate) for use in the CM condition engine.

    Declaration

    Objective-C

    - (BOOL)setTimeProperty:(nonnull NSDate *)value
                 forKey:(nonnull NSString *)name
                  error:(NSError *_Nullable *_Nullable)error;

    Swift

    func setTimeProperty(_ value: Date, forKey name: String) throws

    Parameters

    value

    The property value
    name

    The property key/name. Can be used in conditions as “name” or “custom_name”
    error

    Any errors encountered setting the property

    Return Value

    True if call was successful. An error will be returned/thrown if false.

  • Set a set of custom or well-known properties from JSON formatted data.

    The JSON object should be a single level JSON object, with string keys and bool, string or number values.

    On an issue, it will skip they problematic key/value pair, but continue on and parse as many supported key/value pairs as possible.

    All JSON number values are parsed into float64 values (including integers).

    Declaration

    Objective-C

    - (BOOL)setPropertiesFromJson:(nonnull NSData *)jsonData
                        error:(NSError *_Nullable *_Nullable)error;

    Swift

    func setPropertiesFromJson(_ jsonData: Data) throws

    Parameters

    jsonData

    The json data, in the format described above
    error

    Any errors encountered setting these properties. An error does not necessarily indicate that all fields failed, just that some field(s) failed.

    Return Value

    True if call was successful. An error will be returned/thrown if false.

Notifications

  • Requests a person’s authorization to allow local and remote notifications for your app, using the standard system prompt to the user.

    This API calls the system’s requestAuthorizationWithOptions. If the user approves authorization, Critical Moments will schedule any queued notifications.

    Declaration

    Objective-C

    - (void)requestNotificationPermissionWithCompletionHandler:
    (void (^_Nullable)(BOOL, BOOL, NSError *_Nullable))completionHandler;

    Swift

    func requestNotificationPermission() async throws -> (Bool, Bool)

    Parameters

    completionHandler

    Optional. In swift, return 2 values from an async call to this function. This is returned after permissions are granted or denied in the prompt. Returns two values. The first BOOL indicates if a permission prompt was shown. The second BOOL indicates if the user allowed notifications.