Inherits from NSObject
Declared in SFManager.h

Overview

Splitforce iOS top-level class. Provides synchronisation with Splitforce backend
and configuration of settings.

Tasks

Settings and Configuration

Access to the SFManager object

  • + currentManager

    For convenience, this class exposes a current manager instance.
    This will be set to the first manager that is instantiated in managerWithApplicationId:applicationKey:
    or managerWithApplicationId:applicationKey:completionBlock
    It is a programming error to retrieve this manager before the first manager has been instantiated.
    Doing so will raise an Exception.
  • + managerWithApplicationId:applicationKey:

    Connect to the Splitforce backend.
    This method will start a connection to the Splitforce backend. The method returns immediately
    while the connection happens in the background. To get a callback when the manager is completely
    ready, use the managerWithApplicationId:applicationKey:completionBlock method instead.
  • + managerWithApplicationId:applicationKey:completionBlock:

    Asynchronously connect to the Splitforce backend.
    This method will call the completionBlock when either the locally cached variation data
    is ready, or an updated version has been retrieved from the backend. In case of error (e.g. first time
    usage with no network coverage it will call the completionBlock with NO. Otherwise the completionBlock
    will be called with YES.

Class Parameters

  • + setTimeoutInterval:

    Set the timeout for connecting to the Splitforce backend. Note that an initial connect requires two round trips, so
    the max time any method would block or the max time for a callback to be called may be twice this value. Note also
    that you must set this parameter before initialising the manager connection, hence this is a class method. Changing
    the value after the manager has been established will have no effect.
  • + setDebugMode:

    Switching on debugMode will provide more detailed logs on the console and should be switched on for all DEBUG builds.
    Debug mode also enables ‘Shake to Variation’ which allows you to force particular variations to be used from the UI within the app.
    Simply shake the device to get a menu of Experiments and Variations.
  • + disableShakeToVariation

    Suppresses the shake-to-variation behaviour in Debug Mode. You can programatically invoke the Variation-selection Action Sheet
    using -[showVariationSelection]
  •   shakeToVariationDidChangeVariationBlock

    When using Shake to Variation, you may need to reinitialise singletons or instances that were configured with the data.
    If so then you can do that within this block.

         property
  • + setPersistDefaultCohort:

    By default, experiments are revalidated on-demand, so if the user has been placed in the default cohort due to lack of connectivity, then they will join the correct cohort soon after the data becomes available. If you would prefer to ensure users always get the same implementation, then set this parameter to YES and we will persist the state that these users are in the default cohort, and therefore will not have experiments applied.
  • + setIdentifyCohortBlock:

    The Cohort Identifier is a dictionary with Experiment Names for keys and Variation Names for values.
    Set this block before instantiating the SFManager. This block will then be called on the main thread
    when the cohort has been established. The Cohort Identifier may be useful for interfacing with third
    party or bespoke Analytics services for example.
  • + setWillUseCohortIdentifierBlock:

    The Cohort Identifier is a dictionary with Experiment Names for keys and Variation Names for values.
    Set this block before instantiating the SFManager. This block will then be called on the main thread
    when the cohort has been established. The Cohort Identifier may be useful for interfacing with third
    party or bespoke Analytics services for example.

    Also note that the default cohort is represented as an empty dictionary.
  • + setCustomTargetingKey:withBlock:

    When you define custom Segmentation/Targeting Conditions on the website, this allows you to target
    variations based on runtime data. To pass your custom data into the targeting engine, call setCustomTargetingKey:withBlock: before intialising the splitforce library.
    The splitforce library will then execute valueBlock when required, and pass the return value into the targeting engine.
    For example, to return the user’s gender from a global user object:
    [SFManager setCustomTargetingKey:@“gender” withBlock:^{
    return [UserManager.currentUser gender];
    }];

Running Experiments

  • – experimentNamed:applyVariationBlock:applyDefaultBlock:

    Get the data for an experiment and apply the variationBlock on the selected variation.
    The SFVariation object provided to the applyVariationBlock will contain the raw data
    in the variationData property. The SFVariation object shall be used when goal conditions
    are met in order to accurately track the variation and result. The - [SFVariation bindVariationToObject:] method
    is provided as a convenience an can be used in conjunction with - [SFManager variationForObject:] to
    retrieve the correct SFVariation object at a later point.

Retrieving a variation for goal submission

Introspection Utilities

Properties

shakeToVariationDidChangeVariationBlock

When using Shake to Variation, you may need to reinitialise singletons or instances that were configured with the data.
If so then you can do that within this block.

@property (nonatomic, copy) SFVoidBlock shakeToVariationDidChangeVariationBlock

Declared In

SFManager.h

updateFrequency

The frequency of sending data to the Splitforce backend.

@property (nonatomic) NSTimeInterval updateFrequency

Declared In

SFManager.h

Class Methods

currentManager

For convenience, this class exposes a current manager instance.
This will be set to the first manager that is instantiated in managerWithApplicationId:applicationKey:
or managerWithApplicationId:applicationKey:completionBlock
It is a programming error to retrieve this manager before the first manager has been instantiated.
Doing so will raise an Exception.

+ (SFManager *)currentManager

Return Value

The current SFManager

Declared In

SFManager.h

disableShakeToVariation

Suppresses the shake-to-variation behaviour in Debug Mode. You can programatically invoke the Variation-selection Action Sheet
using -[showVariationSelection]

+ (void)disableShakeToVariation

Declared In

SFManager.h

frameworkVersion

Get the framework version

+ (NSString *)frameworkVersion

Declared In

SFManager.h

managerWithApplicationId:applicationKey:

Connect to the Splitforce backend.
This method will start a connection to the Splitforce backend. The method returns immediately
while the connection happens in the background. To get a callback when the manager is completely
ready, use the managerWithApplicationId:applicationKey:completionBlock method instead.

+ (SFManager *)managerWithApplicationId:(NSString *)applicationId applicationKey:(NSString *)applicationKey

Parameters

applicationId

The Application Id provided by the Splitforce Web server.

applicationKey

The Application Key provided by the Splitforce Web server.

Return Value

An SFManager object connected to the specified applicationId.

Discussion

There are a number of different issues to be aware of when setting up the Splitfore connection.
Firstly, if you apply an experiment before the connection is established, then the experimentNamed:applyVariationBlock:errorBlock
method will block until the manager is ready (or has failed) - to prevent blocking the main thread, initialize the manager with the
managedWithApplicationId:applicationKey:completionBlock method instead.

Secondly, if an experiment is applied when the manager has failed to connect, this user will join the “default” cohort and see the
error block variation. See the property persistDefaultCohort for details on the behaviour in this case.

Finally, if there is cached data, then that is used even if the connection fails to get new data.

In general - as long as the user has a functioning internet connection the first time they run the application, then
there will be no issues. You may decide that running your application without an active splitforce connection is
undesirable - in which case the managerWithApplicationId:applicationKey:completionBlock method should be used to ensure
that the initial connection has been made before proceeding further into your aplication.

Declared In

SFManager.h

managerWithApplicationId:applicationKey:completionBlock:

Asynchronously connect to the Splitforce backend.
This method will call the completionBlock when either the locally cached variation data
is ready, or an updated version has been retrieved from the backend. In case of error (e.g. first time
usage with no network coverage it will call the completionBlock with NO. Otherwise the completionBlock
will be called with YES.

+ (SFManager *)managerWithApplicationId:(NSString *)applicationId applicationKey:(NSString *)applicationKey completionBlock:(SFBooleanBlock)completionBlock

Parameters

applicationId

The Application Id provided by the Splitforce Web server.

applicationKey

The Application Key provided by the Splitforce Web server.

completionBlock

An SFBooleanBlock which will be called when the SFManager has been connected, or failed to connect.

Return Value

An SFManager object connected to the specified applicationId.

Discussion

There are a number of different issues to be aware of when setting up the Splitfore connection.
Firstly, if you apply an experiment before the connection is established, then the experimentNamed:applyVariationBlock:errorBlock
method will queue variation blocks until the manager is ready (or has failed) - this can lead to the user interface being updated
in front of the user if the data completes loading after the experiment has been applied. Waiting for the completionBlock to be called
before applying experiments will resolve this issue.

Secondly, if an experiment is applied when the manager has failed to connect, this user will join the “default” cohort and see the
error block variation. See the property persistDefaultCohort for details on the behaviour in this case.

Finally, if there is cached data, then that is used even if the connection fails to get new data.

In general - as long as the user has a functioning internet connection the first time they run the application, then
there will be no issues. You may decide that running your application without an active splitforce connection is
undesirable - in which case the managerWithApplicationId:applicationKey:completionBlock method should be used to ensure
that the initial connection has been made before proceeding further into your aplication.

The method returns the SFManager object that will be returned by SFManager.currentManager. Note that calling methods on the returned SFManager,
or calling methods on SFManager.currentManager is unsupported prior to the completionBlock being called and the behaviour is undefined.

Declared In

SFManager.h

setCustomTargetingKey:withBlock:

When you define custom Segmentation/Targeting Conditions on the website, this allows you to target
variations based on runtime data. To pass your custom data into the targeting engine, call setCustomTargetingKey:withBlock: before intialising the splitforce library.
The splitforce library will then execute valueBlock when required, and pass the return value into the targeting engine.
For example, to return the user’s gender from a global user object:
[SFManager setCustomTargetingKey:@“gender” withBlock:^{
return [UserManager.currentUser gender];
}];

+ (void)setCustomTargetingKey:(NSString *)key withBlock:(SFTargetingValueBlock)valueBlock

Declared In

SFManager.h

setDebugMode:

Switching on debugMode will provide more detailed logs on the console and should be switched on for all DEBUG builds.
Debug mode also enables ‘Shake to Variation’ which allows you to force particular variations to be used from the UI within the app.
Simply shake the device to get a menu of Experiments and Variations.

+ (void)setDebugMode:(BOOL)debugMode

Declared In

SFManager.h

setIdentifyCohortBlock:

The Cohort Identifier is a dictionary with Experiment Names for keys and Variation Names for values.
Set this block before instantiating the SFManager. This block will then be called on the main thread
when the cohort has been established. The Cohort Identifier may be useful for interfacing with third
party or bespoke Analytics services for example.

+ (void)setIdentifyCohortBlock:(SFCohortIdentifierBlock)identifyCohortBlock

Discussion

Also note that the default cohort is represented as an empty dictionary.

Declared In

SFManager.h

setPersistDefaultCohort:

By default, experiments are revalidated on-demand, so if the user has been placed in the default cohort due to lack of connectivity, then they will join the correct cohort soon after the data becomes available. If you would prefer to ensure users always get the same implementation, then set this parameter to YES and we will persist the state that these users are in the default cohort, and therefore will not have experiments applied.

+ (void)setPersistDefaultCohort:(BOOL)persistDefaultCohort

Declared In

SFManager.h

setTimeoutInterval:

Set the timeout for connecting to the Splitforce backend. Note that an initial connect requires two round trips, so
the max time any method would block or the max time for a callback to be called may be twice this value. Note also
that you must set this parameter before initialising the manager connection, hence this is a class method. Changing
the value after the manager has been established will have no effect.

+ (void)setTimeoutInterval:(NSTimeInterval)timeoutInterval

Parameters

timeoutInterval

The length of time in seconds for network timeouts. The default is 15s.

Declared In

SFManager.h

setWillUseCohortIdentifierBlock:

The Cohort Identifier is a dictionary with Experiment Names for keys and Variation Names for values.
Set this block before instantiating the SFManager. This block will then be called on the main thread
when the cohort has been established. The Cohort Identifier may be useful for interfacing with third
party or bespoke Analytics services for example.

Also note that the default cohort is represented as an empty dictionary.

+ (void)setWillUseCohortIdentifierBlock:(SFWillUseCohortIdentifierBlock)willUseCohortIdentifierBlock

Discussion

When running in Debug mode, your cohort modification block will be called before any Shake to Variation choice is applied. That is, Shake to Variation takes precedence over cohort modifications made in this block.

Declared In

SFManager.h

Instance Methods

allExperimentNames

Get the list of known experiment names

- (NSArray *)allExperimentNames

Declared In

SFManager.h

experimentNamed:applyVariationBlock:applyDefaultBlock:

Get the data for an experiment and apply the variationBlock on the selected variation.
The SFVariation object provided to the applyVariationBlock will contain the raw data
in the variationData property. The SFVariation object shall be used when goal conditions
are met in order to accurately track the variation and result. The - [SFVariation bindVariationToObject:] method
is provided as a convenience an can be used in conjunction with - [SFManager variationForObject:] to
retrieve the correct SFVariation object at a later point.

- (void)experimentNamed:(NSString *)experimentName applyVariationBlock:(SFExperimentVariationBlock)variationBlock applyDefaultBlock:(SFErrorBlock)defaultBlock

Parameters

experimentName

The name of an experiment defined on the Splitforce Web Server.

variationBlock

An SFExperimentVariationBlock which will be called when there is valid data for this experiment

defaultBlock

An SFErrorBlock which will be called if there is no valid data for this experiment. The NSError parameter will indicate the reason for no data. You should configure a default version of your variation in this block.

Discussion

The default block should be used to configure default settings for your user. The default block can be called
if there is no connection to the splitforce servers, and no cached content available for your users.

Declared In

SFManager.h

showVariationSelectionInView:

Programatically invoke the ‘shake to variation’ behaviour. Only available in Debug Mode.

- (void)showVariationSelectionInView:(UIView *)view

Declared In

SFManager.h

variationForExperimentNamed:

Convenience method to retrieve the SFVariation object for the most recent application of an experiment.

- (SFVariation *)variationForExperimentNamed:(NSString *)experimentName

Parameters

experimentName

An NSString object matching the experimentName of a previously applied experiment.

Return Value

The SFVariation object which was most recently created for an application of this experiment

Declared In

SFManager.h

variationNamesForExperiment:

Get the list of known variation names for a particular experiment

- (NSArray *)variationNamesForExperiment:(NSString *)experimentName

Declared In

SFManager.h