io.split.client

Interface SplitClient

All Known Implementing Classes:

AlwaysReturnControlSplitClient, LocalhostSplitClient, LocalhostSplitClientAndFactory, SplitClientImpl

public interface SplitClient

Created by adilaijaz on 5/8/15.

Method Summary

Modifier and Type	Method and Description
void	blockUntilReady() The SDK kicks off background threads to download data necessary for using the SDK.
void	destroy() Destroys the background processes and clears the cache, releasing the resources used by the any instances of SplitClient or SplitManager generated by the client's parent SplitFactory
String	getTreatment(Key key, String split, Map<String,Object> attributes) To understand why this method is useful, consider the following simple Split as an example: if user is in segment employees then split 100%:on else if user is in segment all then split 20%:on,80%:off There are two concepts here: matching and bucketing.
String	getTreatment(String key, String split) Returns the treatment to show this key for this feature.
String	getTreatment(String key, String split, Map<String,Object> attributes) This method is useful when you want to determine the treatment to show to an customer (user, account etc.) based on an attribute of that customer instead of it's key.
SplitResult	getTreatmentWithConfig(Key key, String split, Map<String,Object> attributes) Same as getTreatment(Key, String, Map) but it returns the configuration associated to the matching treatment if any.
SplitResult	getTreatmentWithConfig(String key, String split) Same as getTreatment(String, String) but it returns the configuration associated to the matching treatment if any.
SplitResult	getTreatmentWithConfig(String key, String split, Map<String,Object> attributes) Same as getTreatment(String, String, Map) but it returns the configuration associated to the matching treatment if any.
boolean	track(String key, String trafficType, String eventType) Enqueue a new event to be sent to split data collection services Example: client.track(“account”, “Split Software”, “checkout”)
boolean	track(String key, String trafficType, String eventType, double value) Enqueue a new event to be sent to split data collection services Example: client.track(“account”, “Split Software”, “checkout”, 200.00)
boolean	track(String key, String trafficType, String eventType, double value, Map<String,Object> properties) Enqueue a new event to be sent to split data collection services Example: client.track(“account”, “Split Software”, “checkout”, 123, Collections.singletonMap("age", 23))
boolean	track(String key, String trafficType, String eventType, Map<String,Object> properties) Enqueue a new event to be sent to split data collection services Example: client.track(“account”, “Split Software”, “checkout”, Collections.singletonMap("age", 23))

Method Detail

getTreatment

String getTreatment(String key,
                    String split)

Returns the treatment to show this key for this feature. The set of treatments for a feature can be configured on the Split web console.

This method returns the string 'control' if:

1. Any of the parameters were null
2. There was an exception in evaluating the treatment
3. The SDK does not know of the existence of this feature
4. The feature was deleted through the web console.

'control' is a reserved treatment (you cannot create a treatment with the same name) to highlight these exceptional circumstances.

The sdk returns the default treatment of this feature if:

1. The feature was killed
2. The key did not match any of the conditions in the feature roll-out plan

The default treatment of a feature is set on the Split web console.

This method does not throw any exceptions. It also never returns null.

Parameters:

key - a unique key of your customer (e.g. user_id, user_email, account_id, etc.) MUST not be null.

split - the feature we want to evaluate. MUST NOT be null.

Returns:

the evaluated treatment, the default treatment of this feature, or 'control'.

getTreatment

String getTreatment(String key,
                    String split,
                    Map<String,Object> attributes)

This method is useful when you want to determine the treatment to show to an customer (user, account etc.) based on an attribute of that customer instead of it's key.

Examples include showing a different treatment to users on trial plan vs. premium plan. Another example is to show a different treatment to users created after a certain date.

Parameters:

key - a unique key of your customer (e.g. user_id, user_email, account_id, etc.) MUST not be null.

split - the feature we want to evaluate. MUST NOT be null.

attributes - of the customer (user, account etc.) to use in evaluation. Can be null or empty.

Returns:

the evaluated treatment, the default treatment of this feature, or 'control'.

getTreatment

String getTreatment(Key key,
                    String split,
                    Map<String,Object> attributes)

To understand why this method is useful, consider the following simple Split as an example: if user is in segment employees then split 100%:on else if user is in segment all then split 20%:on,80%:off There are two concepts here: matching and bucketing. Matching refers to ‘user is in segment employees’ or ‘user is in segment all’ whereas bucketing refers to ‘100%:on’ or ‘20%:on,80%:off’. By default, the same customer key is used for both matching and bucketing. However, for some advanced use cases, you may want to use different keys. For such cases, use this method. As an example, suppose you want to rollout to percentages of users in specific accounts. You can achieve that by matching via account id, but bucketing by user id. Another example is when you want to ensure that a user continues to get the same treatment after they sign up for your product that they used to get when they were simply a visitor to your site. In that case, before they sign up, you can use their visitor id for both matching and bucketing, but post log-in you can use their user id for matching and visitor id for bucketing.

Parameters:

key - the matching and bucketing keys. MUST NOT be null.

split - the feature we want to evaluate. MUST NOT be null.

attributes - of the entity (user, account etc.) to use in evaluation. Can be null or empty.

Returns:

the evaluated treatment, the default treatment of this feature, or 'control'.

getTreatmentWithConfig

SplitResult getTreatmentWithConfig(String key,
                                   String split)

Same as getTreatment(String, String) but it returns the configuration associated to the matching treatment if any. Otherwise SplitResult.configurations() will be null.

Examples include showing a different treatment to users on trial plan vs. premium plan. Another example is to show a different treatment to users created after a certain date.

Parameters:

key - a unique key of your customer (e.g. user_id, user_email, account_id, etc.) MUST not be null.

split - the feature we want to evaluate. MUST NOT be null.

Returns:

SplitResult containing the evaluated treatment (the default treatment of this feature, or 'control') and a configuration associated to this treatment if set.

getTreatmentWithConfig

SplitResult getTreatmentWithConfig(String key,
                                   String split,
                                   Map<String,Object> attributes)

Same as getTreatment(String, String, Map) but it returns the configuration associated to the matching treatment if any. Otherwise SplitResult.configurations() will be null.

Examples include showing a different treatment to users on trial plan vs. premium plan. Another example is to show a different treatment to users created after a certain date.

Parameters:

key - a unique key of your customer (e.g. user_id, user_email, account_id, etc.) MUST not be null.

split - the feature we want to evaluate. MUST NOT be null.

attributes - of the customer (user, account etc.) to use in evaluation. Can be null or empty.

Returns:

SplitResult containing the evaluated treatment (the default treatment of this feature, or 'control') and a configuration associated to this treatment if set.

getTreatmentWithConfig

SplitResult getTreatmentWithConfig(Key key,
                                   String split,
                                   Map<String,Object> attributes)

Same as getTreatment(Key, String, Map) but it returns the configuration associated to the matching treatment if any. Otherwise SplitResult.configurations() will be null.

Parameters:

key - the matching and bucketing keys. MUST NOT be null.

split - the feature we want to evaluate. MUST NOT be null.

attributes - of the entity (user, account etc.) to use in evaluation. Can be null or empty.

Returns:

SplitResult containing the evaluated treatment (the default treatment of this feature, or 'control') and a configuration associated to this treatment if set.

destroy

void destroy()

Destroys the background processes and clears the cache, releasing the resources used by the any instances of SplitClient or SplitManager generated by the client's parent SplitFactory

track

boolean track(String key,
              String trafficType,
              String eventType)

Enqueue a new event to be sent to split data collection services Example: client.track(“account”, “Split Software”, “checkout”)

Parameters:

key - the identifier of the entity

trafficType - the type of the event

eventType - the type of the event

Returns:

true if the track was successful, false otherwise

track

boolean track(String key,
              String trafficType,
              String eventType,
              double value)

Enqueue a new event to be sent to split data collection services Example: client.track(“account”, “Split Software”, “checkout”, 200.00)

Parameters:

key - the identifier of the entity

trafficType - the type of the event

eventType - the type of the event

value - the value of the event

Returns:

true if the track was successful, false otherwise

track

boolean track(String key,
              String trafficType,
              String eventType,
              Map<String,Object> properties)

Enqueue a new event to be sent to split data collection services Example: client.track(“account”, “Split Software”, “checkout”, Collections.singletonMap("age", 23))

Parameters:

key - the identifier of the entity

trafficType - the type of the event

eventType - the type of the event

value - the value of the event

Returns:

true if the track was successful, false otherwise

track

boolean track(String key,
              String trafficType,
              String eventType,
              double value,
              Map<String,Object> properties)

Enqueue a new event to be sent to split data collection services Example: client.track(“account”, “Split Software”, “checkout”, 123, Collections.singletonMap("age", 23))

Parameters:

key - the identifier of the entity

trafficType - the type of the event

eventType - the type of the event

value - the value of the event

Returns:

true if the track was successful, false otherwise

blockUntilReady

void blockUntilReady()
              throws TimeoutException,
                     InterruptedException

The SDK kicks off background threads to download data necessary for using the SDK. You can choose to block until the SDK has downloaded split definitions so that you will not get the 'control' treatment.

If the download is not successful in the time period set on SplitClientConfig.Builder.setBlockUntilReadyTimeout(int), a TimeoutException will be thrown.

Throws:

TimeoutException

InterruptedException