# 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

- `+startApptimizeWithApplicationKey:`

  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.

- `+startApptimizeWithApplicationKey:options:`

  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)

  #### Parameters

  `applicationKey` | The application key for this app as provided by the Apptimize dashboard.
  `options` | A dictionary containing some combination of `ApptimizeDevicePairingOption`, `ApptimizeLogLevelOption`, `ApptimizeDelayUntilTestsAreAvailableOption`, `ApptimizeEnableThirdPartyEventImportingOption`, `ApptimizeEnableThirdPartyEventExportingOption`, `ApptimizeEnableInteractionEventCollectionOption`, `ApptimizeForceVariantsShowWinnersAndInstantUpdatesOption`, `ApptimizeServerRegionOption`, `ApptimizeAppGroupOption` and their respective values. May be nil.

- `+setCustomerUserID:`

  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.

- `+customerUserID`

  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.

- `+apptimizeAnonUserID`

  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`

  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

- `+setOffline:`

  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.

- `+isOffline`

  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.

- `+setLogLevel:`

  Set the log level of the Apptimize library.

  #### Declaration

  Objective-C

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

  Swift

      class func setLogLevel(_ logLevel: String)

  #### Parameters

  `logLevel` | One of `ApptimizeLogLevelVerbose`, `ApptimizeLogLevelDebug`, `ApptimizeLogLevelInfo`, `ApptimizeLogLevelWarn`, `ApptimizeLogLevelError` or `ApptimizeLogLevelOff`.

- `+metadataState`

  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

- `+metadataSequenceNumber`

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

  #### Declaration

  Objective-C

      + (int)metadataSequenceNumber;

  Swift

      class func metadataSequenceNumber() -> Int32

### Event handling

- `+track:`

  Generate an event.

  #### Declaration

  Objective-C

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

  Swift

      class func track(_ eventName: String)

  #### Parameters

  `eventName` | The name of the event.

- `+track:value:`

  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.

- `+libraryVersion`

  #### 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).

- `+userID`

  #### 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.

- `+partnerID`

  #### 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

- `+setPilotTargetingID:`

  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.

- `+pilotTargetingID`

  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.

- `+setMixpanelIdentity:`

  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

- `+waitForTestsToBecomeAvailable:`

  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.

- `+runTest:withBaseline:variations:andOptions:`

  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.

- `+runTest:withBaseline:andVariations:`

  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.

- `+runTest:withBaseline:apptimizeCodeBlocks:andOptions:`

  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.

- `+runTest:withBaseline:andApptimizeCodeBlocks:`

  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.

- `+isFeatureFlagOn:`

  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.

- `+testInfo`

  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.

- `+instantUpdateAndWinnerInfo`

  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

- `+setUserAttributeString:forKey:`

  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.

- `+setUserAttributeInteger:forKey:`

  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.

- `+setUserAttributeDouble:forKey:`

  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.

- `+setUserAttributeBool:forKey:`

  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.

- `+removeUserAttributeForKey:`

  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.

- `+removeAllUserAttributes`

  Remove all user defined attributes.

  #### Declaration

  Objective-C

      + (void)removeAllUserAttributes;

  Swift

      class func removeAllUserAttributes()

- `+userAttributeStringForKey:`

  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.

- `+userAttributeIntegerForKey:`

  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.

- `+userAttributeDoubleForKey:`

  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.

- `+userAttributeBoolForKey:`

  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

- `+forceVariant:`

  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.

- `+clearForcedVariant:`

  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.

- `+clearAllForcedVariants`

  Cancel all forced variants.

  #### Declaration

  Objective-C

      + (void)clearAllForcedVariants;

  Swift

      class func clearAllForcedVariants()

- `+getVariants`

  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.

© 2025 Apptimize Inc.. All rights reserved. (Last updated: 2025-10-10)

Generated by jazzy ♪♫ v0.14.3, a Realm project.