Package io.split.client

Interface SplitClient

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method 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 {@link 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 {@link 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 {@link 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