Split (split v0.2.1-rc.0)

The Split.io Elixir thin client.

This module provides a simple API to interact with the Split.io service via the Split Daemon (splitd).

Adding Split to Your Supervision Tree

The most basic approach is to add Split as a child of your application's top-most supervisor, i.e. lib/my_app/application.ex.

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      # ... other children ...
      {Split, [socket_path: "/var/run/split.sock"]}
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

You can also start Split dynamically by calling Split.Supervisor.start_link/1:

Split.Supervisor.start_link(opts)

Options

Split takes a number of keyword arguments as options when starting. The following options are available:

:socket_path: OPTIONAL The path to the splitd socket file. Default is "/var/run/splitd.sock".
:pool_size: OPTIONAL The size of the pool of connections to the splitd daemon. Default is the number of online schedulers in the Erlang VM (See: https://www.erlang.org/doc/apps/erts/erl_cmd.html).
:connect_timeout: OPTIONAL The timeout in milliseconds to connect to the splitd daemon. Default is 1000.

Using the API

Once you have started Split, you are ready to start interacting with the Split.io splitd's daemon to access feature flags and configurations.

Split.get_treatment("user_key", "feature_name")

Summary

Types

attributes()

A map of attributes to use when evaluating feature flags.

option()

An option that can be provided when starting Split. See options for more information.

options()

Options to start the Split application.

properties()

A map of properties to use when tracking an event.

split_key()

The traffic type identifier. It can be either a string or a map with a matching key and an optional bucketing key.

Functions

child_spec(options)

Builds a child specification to use in a Supervisor.

get_treatment(key, feature_name, attributes \\ %{})

Gets the treatment string for a given key, feature flag name and optional attributes.

get_treatment_with_config(key, feature_name, attributes \\ %{})

Gets the treatment with config for a given key, feature flag name and optional attributes.

get_treatments(key, feature_names, attributes \\ %{})

Gets a map of feature flag names to treatments for a given key, list of feature flag names and optional attributes.

get_treatments_by_flag_set(key, flag_set_name, attributes \\ %{})

Gets a map of feature flag names to treatment strings for a given key, flag set name and optional attributes.

get_treatments_by_flag_sets(key, flag_set_names, attributes \\ %{})

Gets a map of feature flag names to treatment strings for a given key, flag set name and optional attributes.

get_treatments_with_config(key, feature_names, attributes \\ %{})

Gets a map of feature flag names to treatments with config for a given key, list of feature flag names and optional attributes.

get_treatments_with_config_by_flag_set(key, flag_set_name, attributes \\ %{})

Gets a map of feature flag names to treatments with config for a given key, flag set name and optional attributes.

get_treatments_with_config_by_flag_sets(key, flag_set_names, attributes \\ %{})

Gets a map of feature flag names to treatments with config for a given key, flag set name and optional attributes.

split(name)

Gets the data of a given feature flag name in SplitView format.

split_names()

Gets the list of all feature flag names.

splits()

Gets the data of all feature flags in SplitView format.

track(key, traffic_type, event_type, value \\ nil, properties \\ %{})

Tracks an event for a given key, traffic type, event type, and optional numeric value and map of properties. Returns true if the event was successfully tracked, or false otherwise, e.g. if the Split daemon is not running or cannot be reached.

Types

attributes()

@type attributes() :: %{
  optional(atom() | String.t()) =>
    String.t() | integer() | boolean() | [String.t() | integer()] | nil
}

A map of attributes to use when evaluating feature flags.

option()

@type option() ::
  {:socket_path, String.t()}
  | {:pool_size, non_neg_integer()}
  | {:connect_timeout, non_neg_integer()}

An option that can be provided when starting Split. See options for more information.

options()

@type options() :: [option()]

Options to start the Split application.

properties()

@type properties() :: %{
  optional(atom() | String.t()) => String.t() | integer() | boolean() | nil
}

A map of properties to use when tracking an event.

split_key()

@type split_key() ::
  String.t()
  | %{:matchingKey => String.t(), optional(:bucketingKey) => String.t() | nil}

The traffic type identifier. It can be either a string or a map with a matching key and an optional bucketing key.

Functions

child_spec(options)

@spec child_spec(options()) :: Supervisor.child_spec()

Builds a child specification to use in a Supervisor.

Normally not called directly by your code. Instead, it will be called by your application's Supervisor once you add Split to its supervision tree.

get_treatment(key, feature_name, attributes \\ %{})

@spec get_treatment(split_key(), String.t(), attributes()) :: String.t()

Gets the treatment string for a given key, feature flag name and optional attributes.

Examples

iex> Split.get_treatment("user_id", "located_in_usa")
"off"
iex> Split.get_treatment("user_id", "located_in_usa", %{country: "USA"})
"on"

get_treatment_with_config(key, feature_name, attributes \\ %{})

@spec get_treatment_with_config(split_key(), String.t(), attributes()) ::
  Split.TreatmentWithConfig.t()

Gets the treatment with config for a given key, feature flag name and optional attributes.

Examples

iex> Split.get_treatment_with_config("user_id", "located_in_usa")
%Split.TreatmentWithConfig{treatment: "off", config: nil}
iex> Split.get_treatment("user_id", "located_in_usa", %{country: "USA"})
%Split.TreatmentWithConfig{treatment: "on", config: nil}

get_treatments(key, feature_names, attributes \\ %{})

@spec get_treatments(split_key(), [String.t()], attributes()) :: %{
  required(String.t()) => String.t()
}

Gets a map of feature flag names to treatments for a given key, list of feature flag names and optional attributes.

Examples

iex> Split.get_treatments("user_id", ["located_in_usa"])
%{"located_in_usa" => "off"}
iex> Split.get_treatments("user_id", ["located_in_usa"], %{country: "USA"})
%{"located_in_usa" => "on"}

get_treatments_by_flag_set(key, flag_set_name, attributes \\ %{})

@spec get_treatments_by_flag_set(split_key(), String.t(), attributes()) :: %{
  required(String.t()) => String.t()
}

Gets a map of feature flag names to treatment strings for a given key, flag set name and optional attributes.

Examples

iex> Split.get_treatments_by_flag_set("user_id", "frontend_flags")
%{"located_in_usa" => "off"}
iex> Split.get_treatments_by_flag_set("user_id", "frontend_flags", %{country: "USA"})
%{"located_in_usa" => "on"}

get_treatments_by_flag_sets(key, flag_set_names, attributes \\ %{})

@spec get_treatments_by_flag_sets(split_key(), [String.t()], attributes()) :: %{
  required(String.t()) => String.t()
}

Gets a map of feature flag names to treatment strings for a given key, flag set name and optional attributes.

Examples

iex> Split.get_treatments_by_flag_sets("user_id", ["frontend_flags", "backend_flags"])
%{"located_in_usa" => "off"}
iex> Split.get_treatments_by_flag_sets("user_id", ["frontend_flags", "backend_flags"], %{country: "USA"})
%{"located_in_usa" => "on"}

get_treatments_with_config(key, feature_names, attributes \\ %{})

@spec get_treatments_with_config(split_key(), [String.t()], attributes()) :: %{
  required(String.t()) => Split.TreatmentWithConfig.t()
}

Gets a map of feature flag names to treatments with config for a given key, list of feature flag names and optional attributes.

Examples

iex> Split.get_treatments_with_config("user_id", ["located_in_usa"])
%{"located_in_usa" => %Split.TreatmentWithConfig{treatment: "off", config: nil}}
iex> Split.get_treatments_with_config("user_id", ["located_in_usa"], %{country: "USA"})
%{"located_in_usa" => %Split.TreatmentWithConfig{treatment: "on", config: nil}}

get_treatments_with_config_by_flag_set(key, flag_set_name, attributes \\ %{})

@spec get_treatments_with_config_by_flag_set(
  split_key(),
  String.t(),
  attributes()
) :: %{required(String.t()) => Split.TreatmentWithConfig.t()}

Gets a map of feature flag names to treatments with config for a given key, flag set name and optional attributes.

Examples

iex> Split.get_treatments_with_config_by_flag_set("user_id", "frontend_flags")
%{"located_in_usa" => %Split.TreatmentWithConfig{treatment: "off", config: nil}}
iex> Split.get_treatments_with_config_by_flag_set("user_id", "frontend_flags", %{country: "USA"})
%{"located_in_usa" => %Split.TreatmentWithConfig{treatment: "on", config: nil}}

get_treatments_with_config_by_flag_sets(key, flag_set_names, attributes \\ %{})

@spec get_treatments_with_config_by_flag_sets(
  split_key(),
  [String.t()],
  attributes()
) :: %{required(String.t()) => Split.TreatmentWithConfig.t()}

Gets a map of feature flag names to treatments with config for a given key, flag set name and optional attributes.

Examples

iex> Split.get_treatments_with_config_by_flag_sets("user_id", ["frontend_flags", "backend_flags"])
%{"located_in_usa" => %Split.TreatmentWithConfig{treatment: "off", config: nil}}
iex> Split.get_treatments_with_config_by_flag_sets("user_id", ["frontend_flags", "backend_flags"], %{country: "USA"})
%{"located_in_usa" => %Split.TreatmentWithConfig{treatment: "on", config: nil}}

split(name)

@spec split(String.t()) :: Split.SplitView.t() | nil

Gets the data of a given feature flag name in SplitView format.

Examples

iex> Split.split("located_in_usa")
%Split.SplitView{
  name: "located_in_usa",
  traffic_type: "user",
  killed: false,
  treatments: ["on", "off"],
  change_number: 123456,
  configs: %{ "on" => nil, "off" => nil },
  default_treatment: "off",
  sets: ["frontend_flags"],
  impressions_disabled: false
}

split_names()

@spec split_names() :: [String.t()]

Gets the list of all feature flag names.

Examples

iex> Split.split_names()
["located_in_usa"]

splits()

@spec splits() :: [Split.SplitView.t()]

Gets the data of all feature flags in SplitView format.

Examples

iex> Split.splits()
[%Split.SplitView{
  name: "located_in_usa",
  traffic_type: "user",
  killed: false,
  treatments: ["on", "off"],
  change_number: 123456,
  configs: %{ "on" => nil, "off" => nil },
  default_treatment: "off",
  sets: ["frontend_flags"],
  impressions_disabled: false
}]

track(key, traffic_type, event_type, value \\ nil, properties \\ %{})

@spec track(split_key(), String.t(), String.t(), number() | nil, properties()) ::
  boolean()

See: https://help.split.io/hc/en-us/articles/26988707417869-Elixir-Thin-Client-SDK#track

Examples

iex> Split.track("user_id", "user", "my-event")
true
iex> Split.track("user_id", "user", "my-event", 42)
true
iex> Split.track("user_id", "user", "my-event", nil, %{property1: "value1"})
true
iex> Split.track("user_id", "user", "my-event", 42, %{property1: "value1"})
true