Apptimize


@interface Apptimize : NSObject

The Apptimize interface is the main interaction point with the Apptimize SDK for developers.

Getting Started

Add your Apptimize App Key to your application’s Info.plist e.g.

 ApptimizeAppKey = "AaaaABbbbBCcccCDdddDEeeeEFfffF" // Type: String; Without quotes.

For more information on how to get started using the Apptimize Library see: https://apptimize.com/docs/installation/ios-installation.html

Starting and stopping Apptimize

  • Start Apptimize with the default options.

    Apptimize should be started on the main thread and can be safely started more than once.

    See

    +[Apptimize startApptimizeWithApplicationKey:options:]

    Declaration

    Objective-C

    + (void)startApptimizeWithApplicationKey:(nonnull NSString *)applicationKey;

    Swift

    class func start(withApplicationKey applicationKey: String)

    Parameters

    applicationKey

    The application key for this app as provided by the Apptimize dashboard.

  • Start Apptimize with custom options.

    Apptimize should be started on the main thread and can be safely started more than once.

    Startup may be delayed whenever device file protection has locked files Apptimize needs to start up. This can happen if your application is launched in the background before the device has been unlocked for the first time after a reboot, or if the default file protection level for the app has been modified to be more secure. In this case, listening for the ApptimizeInitializedNotification will ensure that apptimize is available.

    Declaration

    Objective-C

    + (void)startApptimizeWithApplicationKey:(nullable NSString *)applicationKey
                                 options:
                                     (nullable NSDictionary<NSString *, id> *)
                                         options;

    Swift

    class func start(withApplicationKey applicationKey: String?, options: [String : Any]? = nil)

  • Set the current customer-specified user ID.

    User IDs are arbitrary strings, except that they cannot be the empty string (“”). When the customer-specified user ID is nil, then Apptimize creates and uses an anonymous user ID for tracking purposes. If the customerUserID is set to a non-nil value, then set back to nil, Apptimize will use the same anonymous user ID as before.

    The initial default value of the customer-specified user ID is nil.

    Note: If startup is delayed due to data protection locking files, the customer id change will also be delayed until startup is completed. This means that the change will not be persisted or available via the customerUserID until startup is completed.

    Declaration

    Objective-C

    + (void)setCustomerUserID:(nullable NSString *)customerUserID;

    Swift

    class func setCustomerUserID(_ customerUserID: String?)

    Parameters

    customerUserID

    An NSString object containing the user ID to set. If this is nil, the user ID is set to be anonymous.

  • Get the current customer-specified user ID.

    Note: If startup is delayed due to data protection locking files, the current customer user ID will be unavailable and this function will return nil.

    Declaration

    Objective-C

    + (nullable NSString *)customerUserID;

    Swift

    class func customerUserID() -> String?

    Return Value

    Returns an NSString object containing the currently set customer user ID. If the user is currently anonymous, nil will be returned.

  • Get the current Apptimize-created anonymous user ID.

    This anonymous user ID will be used if-and-only-if the customer-specified user ID is nil. A single anonymous user ID is created. If the customer user ID is set to a non-nil value, then set back to nil, Apptimize will use the same anonymous user ID as before.

    Note: If startup is delayed due to data protection locking files, the current anonymous user ID will be unavailable and this function will return nil.

    Declaration

    Objective-C

    + (nullable NSString *)apptimizeAnonUserID;

    Swift

    class func apptimizeAnonUserID() -> String?

    Return Value

    Returns an NSString object containing the generated anonymous user ID. This value will only be nil if startup is delayed.

  • Disable Apptimize and all of its features for one application session. No tests will run, no data will be logged, and no results will be posted to the Apptimize dashboard.

    Use with caution.

    Declaration

    Objective-C

    + (void)disable;

    Swift

    class func disable()

Configuring Apptimize

  • Set Apptimize to run in offline mode. In offline mode, all network traffic is disabled.

    Specifically, the app will not receive metadata, upload results, or (for debug builds) be able to pair with the Apptimize web dashboard.

    This setting is persistent and stays in effect across sessions.

    You may call setOffline before calling +startApptimizeWithApplicationKey:.

    Declaration

    Objective-C

    + (void)setOffline:(BOOL)offlineFlag;

    Swift

    class func setOffline(_ offlineFlag: Bool)

    Parameters

    offlineFlag

    YES to enable offline mode, NO to disable offline mode.

  • Get the current value of the offline setting

    Declaration

    Objective-C

    + (BOOL)isOffline;

    Swift

    class func isOffline() -> Bool

    Return Value

    Returns YES if Apptimize is currently in offline mode, or NO if Apptimize is not currently set to offline mode.

  • Set the log level of the Apptimize library.

    Declaration

    Objective-C

    + (void)setLogLevel:(nonnull NSString *)logLevel;

    Swift

    class func setLogLevel(_ logLevel: String)

  • Get the current state of the apptimize metadata as a combination of flags.

    See @ApptimizeMetadataStateFlags.

    Declaration

    Objective-C

    + (ApptimizeMetadataStateFlags)metadataState;

    Swift

    class func metadataState() -> ApptimizeMetadataStateFlags

  • Get the sequence number of the current metadata (if any; 0 otherwise)

    Declaration

    Objective-C

    + (int)metadataSequenceNumber;

    Swift

    class func metadataSequenceNumber() -> Int32

Event handling

  • Generate an event.

    Declaration

    Objective-C

    + (void)track:(nonnull NSString *)eventName;

    Swift

    class func track(_ eventName: String)

    Parameters

    eventName

    The name of the event.

  • Generate an event with an associated numeric value.

    Declaration

    Objective-C

    + (void)track:(nonnull NSString *)eventName value:(double)value;

    Swift

    class func track(_ eventName: String, value: Double)

    Parameters

    eventName

    The name of the event.
    value

    The value associated with the event.

SDK information.

  • Declaration

    Objective-C

    + (nonnull NSString *)libraryVersion;

    Swift

    class func libraryVersion() -> String

    Return Value

    Returns the version number of the Apptimize library as a string formatted as major.minor.build (e.g., 1.2.0).

  • Declaration

    Objective-C

    + (nonnull NSString *)userID;

    Swift

    class func userID() -> String

    Return Value

    Returns the ID used by Apptimize to uniquely identify users of the current app.

  • Declaration

    Objective-C

    + (nonnull NSString *)partnerID;

    Swift

    class func partnerID() -> String

    Return Value

    The partner user ID of the current user. This ID should be used for targeting Apptimize users in Mixpanel cohorts

Piloting

  • Sets the pilotTargetingID in order to use the pilot targeting feature available on the Apptimize web dashboard.

    Pilot targeting allows you to select specific pilot targeting IDs and groups of pilot targeting IDs in the Apptimize web dashboard for the purposes of targeting experiments and feature flags to specific app/user instances.

    Setting this value will cause pilot targeting to be recalculated if applicable.

    Declaration

    Objective-C

    + (void)setPilotTargetingID:(nullable NSString *)pilotTargetingID;

    Swift

    class func setPilotTargetingID(_ pilotTargetingID: String?)

    Parameters

    pilotTargetingID

    The string ID to use for targeting pilot users. Resets pilot targeting id if nil value is provided.

  • Retrieves the currently set pilot targeting ID.

    Pilot targeting allows you to select specific pilot targeting IDs and groups of pilot targeting IDs in the Apptimize web dashboard for the purposes of targeting experiments and feature flags to specific app/user instances.

    Setting this value will cause pilot targeting to be recalculated if applicable.

    Declaration

    Objective-C

    + (nullable NSString *)pilotTargetingID;

    Swift

    class func pilotTargetingID() -> String?

    Return Value

    Returns the pilot targeting ID. By default this value is nil. It should be set by your application to enable pilot targeting for the device.

  • Deprecated

    Tells the apptimize SDK what distinct ID has been set in the Mixpanel SDK (via Mixpanel.identify)

    Not needed when using the Objective C Mixpanel SDK; the value passed to [Mixpanel identify:] is picked up automatically. Needed when using the Swift Mixpanel SDK, where this does not happen.

    Setting this value will cause targeting to be recalculated if applicable. This operation is asynchronous, and will trigger enrollment callbacks.

    Declaration

    Objective-C

    + (void)setMixpanelIdentity:(nonnull NSString *)identity;

    Swift

    class func setMixpanelIdentity(_ identity: String)

    Parameters

    identity

    A string identifier matching what is passed to Mixpanel.identify for the current user.

Experiments

  • Wait for the initial set of tests to become available. This method will block for timeout milliseconds (up to 8000) while Apptimize attempts to fetch tests and any related assets.

    This is meant to be used as part of application initialization, usually during a loading screen.

    Declaration

    Objective-C

    + (BOOL)waitForTestsToBecomeAvailable:(double)timeout;

    Swift

    class func waitForTests(toBecomeAvailable timeout: Double) -> Bool

    Parameters

    timeout

    The amount of time to wait before giving up and enrolling in the default variants. Capped at 8000 milliseconds.

  • Run a code block A/B test.

    When this method is called, one of the code block variants or the default code block will be run sychronously in accordance with the A/B test variant this user/device is enrolled in.

    See

    Note: For Swift, use +[Apptimize runTest:withBaseline:apptimizeCodeBlocks:andOptions:]

    Declaration

    Objective-C

    + (void)runTest:(nonnull NSString *)testName
    withBaseline:(nonnull void (^)(void))baselineBlock
      variations:(nonnull NSDictionary<NSString *, void (^)(void)> *)variations
      andOptions:(nullable NSDictionary<NSString *, NSNumber *> *)options;

    Parameters

    testName

    The name of the test to run.
    baselineBlock

    The default code block to execute if we are enrolled in the default variant.
    variations

    A dictionary containing code blocks keyed using strings. The string keys must match the name of the variant set in the Apptimize dashboard.
    options

    Nil or a dictionary containing ApptimizeUpdateMetadataTimeoutOption and a value in milliseconds.

  • Run a code block A/B test.

    This is the same as calling +[Apptimize runTest:withBaseline:variations:andOptions:] with nil for options.

    When this method is called, one of the code block variants or the default code block will be run sychronously in accordance with the A/B test variant this user/device is enrolled in.

    See

    Note: For Swift, use +[Apptimize runTest:withBaseline:apptimizeCodeBlocks:andOptions:]

    Declaration

    Objective-C

    + (void)runTest:(nonnull NSString *)testName
     withBaseline:(nonnull void (^)(void))baselineBlock
    andVariations:
        (nonnull NSDictionary<NSString *, void (^)(void)> *)variations;

    Parameters

    testName

    The name of the test to run.
    baselineBlock

    The default code block to execute if we are enrolled in the default variant.
    variations

    A dictionary containing code blocks keyed using strings. The string keys correspond to the name of the variant set in the Apptimize dashboard.

  • Run a code block A/B test.

    This is the same as +runTest:withBaseline:variations:andOptions: except that instead of taking a dictionary of Objective-C code blocks, it takes an array of ApptimizeCodeBlock objects. This is useful for Swift where using +runTest:withBaseline:variations:andOptions is problematic due to bridging issues.

    When this method is called, one of the code block variants or the default code block will be run sychronously in accordance with the A/B test variant this user/device is enrolled in.

    Declaration

    Objective-C

    + (void)runTest:(nonnull NSString *)testName
           withBaseline:(nonnull void (^)(void))baselineBlock
    apptimizeCodeBlocks:(nonnull NSArray<ApptimizeCodeBlock *> *)codeBlocks
             andOptions:
                 (nullable NSDictionary<NSString *, NSNumber *> *)options;

    Swift

    class func runTest(_ testName: String, withBaseline baselineBlock: @escaping () -> Void, apptimizeCodeBlocks codeBlocks: [ApptimizeCodeBlock], andOptions options: [String : NSNumber]? = nil)

    Parameters

    testName

    The name of the test to run.
    baselineBlock

    The default code block to execute if we are enrolled in the default variant.
    codeBlocks

    An array containing ApptimizeCodeBlock objects. The name of each object corresponds to the name of the variant set in the Apptimize dashboard.
    options

    Nil or a dictionary containing ApptimizeUpdateMetadataTimeoutOption and a value in milliseconds.

  • Run a code block A/B test.

    This is the same as calling +runTest:withBaseline:apptimizeCodeBlocks:andOptions: with nil for options.

    When this method is called, one of the code block variants or the default code block will be run sychronously in accordance with the A/B test variant this user/device is enrolled in.

    Declaration

    Objective-C

    + (void)runTest:(nonnull NSString *)testName
              withBaseline:(nonnull void (^)(void))baselineBlock
    andApptimizeCodeBlocks:(nonnull NSArray<ApptimizeCodeBlock *> *)codeBlocks;

    Swift

    class func runTest(_ testName: String, withBaseline baselineBlock: @escaping () -> Void, andApptimizeCodeBlocks codeBlocks: [ApptimizeCodeBlock])

    Parameters

    testName

    The name of the test to run.
    baselineBlock

    The default code block to execute if we are enrolled in the default variant.
    codeBlocks

    An array containing ApptimizeCodeBlock objects. The name of each object corresponds to the name of the variant set in the Apptimize dashboard.

  • Check whether a given feature flag is enabled or not.

    Declaration

    Objective-C

    + (BOOL)isFeatureFlagOn:(nonnull NSString *)featureFlagName;

    Swift

    class func isFeatureFlag(on featureFlagName: String) -> Bool

    Return Value

    Returns YES if the feature flag is on, NO if it is not.

  • Get information about all Apptimize A/B tests and Feature Flags that the device is enrolled in.

    Note: this does not include information about Apptimize A/B tests or Feature Flags that are running but that the device is not enrolled in.

    Declaration

    Objective-C

    + (nullable NSDictionary<NSString *, id<ApptimizeTestInfo>> *)testInfo;

    Swift

    class func testInfo() -> [String : ApptimizeTestInfo]?

    Return Value

    Returns a dictionary whose keys are the names of all A/B tests and Feature Flags the device is enrolled in, and whose values are ApptimizeTestInfo objects containing information about the test or Feature Flag. If this device is enrolled in no tests, an empty dictionary is returned. If +startApptimizeWithApplicationKey: has not been called yet, nil is returned.

  • Get information about all winning A/B tests and instant updates that the device will show.

    Declaration

    Objective-C

    + (nullable NSDictionary<NSString *, id<ApptimizeInstantUpdateOrWinnerInfo>> *)
    instantUpdateAndWinnerInfo;

    Swift

    class func instantUpdateAndWinnerInfo() -> [String : ApptimizeInstantUpdateOrWinnerInfo]?

    Return Value

    Returns a dictionary whose keys are the names of all A/B tests and instant updates the device has active, and whose values are ApptimizeInstantUpdateOrWinnerInfo objects containing information about the test or instant update. If there are no winners or instant updates, an empty dictionary is returned. If +startApptimizeWithApplicationKey: has not been called yet, nil is returned.

UserAttributes

  • Set a user attribute string to be used for targeting, filtering and segmentation.

    Declaration

    Objective-C

    + (void)setUserAttributeString:(nonnull NSString *)attributeValue
                        forKey:(nonnull NSString *)attributeName;

    Swift

    class func setUserAttributeString(_ attributeValue: String, forKey attributeName: String)

    Parameters

    attributeValue

    The attribute string to set for this app instance.
    attributeName

    The name of the attribute to set.

  • Set a user attribute integer to be used in targeting, filtering and segmentation.

    Declaration

    Objective-C

    + (void)setUserAttributeInteger:(NSInteger)attributeValue
                         forKey:(nonnull NSString *)attributeName;

    Swift

    class func setUserAttributeInteger(_ attributeValue: Int, forKey attributeName: String)

    Parameters

    attributeValue

    The attribute integer to set for this app instance.
    attributeName

    The name of the attribute to set.

  • Set a user attribute double to be used in targeting, filtering and segmentation.

    Declaration

    Objective-C

    + (void)setUserAttributeDouble:(double)attributeValue
                        forKey:(nonnull NSString *)attributeName;

    Swift

    class func setUserAttributeDouble(_ attributeValue: Double, forKey attributeName: String)

    Parameters

    attributeValue

    The attribute double to set for this app instance.
    attributeName

    The name of the attribute to set.

  • Set a user attribute boolean to be used in targeting, filtering and segmentation.

    Declaration

    Objective-C

    + (void)setUserAttributeBool:(BOOL)attributeValue
                      forKey:(nonnull NSString *)attributeName;

    Swift

    class func setUserAttributeBool(_ attributeValue: Bool, forKey attributeName: String)

    Parameters

    attributeValue

    The attribute boolean to set for this app instance.
    attributeName

    The name of the attribute to set.

  • Remove the user defined attribute for a given for key.

    Declaration

    Objective-C

    + (void)removeUserAttributeForKey:(nonnull NSString *)attributeName;

    Swift

    class func removeUserAttribute(forKey attributeName: String)

    Parameters

    attributeName

    The name of the attribute to remove.

  • Remove all user defined attributes.

    Declaration

    Objective-C

    + (void)removeAllUserAttributes;

    Swift

    class func removeAllUserAttributes()

  • Get the currently set string value for an attribute.

    Declaration

    Objective-C

    + (nullable NSString *)userAttributeStringForKey:
    (nonnull NSString *)attributeName;

    Swift

    class func userAttributeString(forKey attributeName: String) -> String?

    Parameters

    attributeName

    The name of the attribute to query.

    Return Value

    Returns the string value associated with the supplied attribute name.

  • Get the currently set integer value for an attribute.

    Declaration

    Objective-C

    + (NSInteger)userAttributeIntegerForKey:(nonnull NSString *)attributeName;

    Swift

    class func userAttributeInteger(forKey attributeName: String) -> Int

    Parameters

    attributeName

    The name of the attribute to query.

    Return Value

    Returns the integer value associated with the supplied attribute name.

  • Get the currently set double value for an attribute.

    Declaration

    Objective-C

    + (double)userAttributeDoubleForKey:(nonnull NSString *)attributeName;

    Swift

    class func userAttributeDouble(forKey attributeName: String) -> Double

    Parameters

    attributeName

    The name of the attribute to query.

    Return Value

    Returns the double value associated with the supplied attribute name.

  • Get the currently set boolean value for an attribute.

    Declaration

    Objective-C

    + (BOOL)userAttributeBoolForKey:(nonnull NSString *)attributeName;

    Swift

    class func userAttributeBool(forKey attributeName: String) -> Bool

    Parameters

    attributeName

    The name of the attribute to query.

    Return Value

    Returns the boolean value associated with the supplied attribute name.

VariantOverrides

  • Force a variant with a given ID to be enabled.

    Once forceVariant is called, Apptimize is placed in a special test mode where it will only enable variants that are forced by forceVariant. All other Feature Flags, A/B Experiments and Instant Updates will appear disabled/off unless a specific variant is forced for those projects. Call forceVariant for each of the variants you want to apply.

    See

    +[Apptimize clearAllForcedVariants] to return Apptimize to normal operation.

    See

    +[Apptimize clearForcedVariant:]

    See

    +[Apptimize getVariants]

    All variants forced using this method will be treated as though they underwent experiment selection, and will be reflected on your results dashboard. Forced variants are persistent across application launches and will not be reset except by calls to +clearForcedVariant:variantID: or +clearAllForcedVariants:.

    Note that ApptimizeForceVariantsShowWinnersAndInstantUpdatesOption determines whether winners and instant-updates will be shown. By default, this setting is off, so change your call to +startApptimizeWithApplicationKey:options:, or via Info.plist to turn it on as needed. The “Advanced Verify” feature on the dashboard will only work when winners and instant-updates are being shown, because “Advanced Verify” works by sending an instant update to the paired device.

    Declaration

    Objective-C

    + (void)forceVariant:(NSInteger)variantID;

    Swift

    class func forceVariant(_ variantID: Int)

    Parameters

    variantID

    The numeric ID of the variant to forcibly enable.

  • Cancel a forced variant.

    Declaration

    Objective-C

    + (void)clearForcedVariant:(NSInteger)variantID;

    Swift

    class func clearForcedVariant(_ variantID: Int)

    Parameters

    variantID

    The numeric ID of the variant to cancel force enabling for.

  • Cancel all forced variants.

    Declaration

    Objective-C

    + (void)clearAllForcedVariants;

    Swift

    class func clearAllForcedVariants()

  • Get a dictionary of information about all available variants.

    The returned dictionary is a mapping of variant IDs (in string format) to another dictionary with the following mappings:

    Key Value Type
    variantName The name of this variant String
    variantID The numeric ID of this variant Integer
    experimentName The name of the experiment associated with this variant String
    experimentID The numeric ID of the experiment associated with this variant Integer

    Declaration

    Objective-C

    + (nullable NSDictionary<NSString *, NSDictionary<NSString *, id> *> *)
    getVariants;

    Swift

    class func getVariants() -> [String : [String : Any]]?

    Return Value

    Returns a dictionary describing each available variant for this app in the format described above. The returned dictionary will be empty if there are no available variants.
    Returns nil if +startApptimizeWithApplicationKey: has not been called.