The ConfigCat Elixir SDK.

ConfigCat provides a Supervisor that must be added to your applications supervision tree and an API for accessing your ConfigCat settings.

Add ConfigCat to Your Supervision Tree

Your application's supervision tree might need to be different, but the most basic approach is to add ConfigCat as a child of your top-most supervisor.

# lib/my_app/application.ex
def start(_type, _args) do
  children = [
    # ... other children ...
    {ConfigCat, [sdk_key: "YOUR SDK KEY"]}
  ]

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

Options

ConfigCat takes a number of keyword arguments:

• sdk_key: REQUIRED The SDK key for accessing your ConfigCat settings. Go to the Connect your application tab to get your SDK key.

  {ConfigCat, [sdk_key: "YOUR SDK KEY"]}

• base_url: OPTIONAL Allows you to specify a custom URL for fetching your ConfigCat settings.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", base_url: "https://my-cdn.example.com"]}

• cache: OPTIONAL Custom cache implementation. By default, ConfigCat uses its own in-memory cache, but you can also provide the name of a module that implements the ConfigCat.ConfigCache behaviour if you want to provide your own cache (e.g. based on Redis). If your cache implementation requires supervision, it is your application's responsibility to provide that.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", cache: MyCustomCacheModule]}

• cache_policy: OPTIONAL Specifies the polling mode used by ConfigCat. Defaults to auto-polling mode with a 60 second poll interval. You can specify a different polling mode or polling interval using ConfigCat.CachePolicy.auto/1, ConfigCat.CachePolicy.lazy/1, or ConfigCat.CachePolicy.manual/0.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", cache_policy: ConfigCat.CachePolicy.manual()]}

• connect_timeout_milliseconds: OPTIONAL timeout for establishing a TCP or SSL connection, in milliseconds. Default is 8000.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", connect_timeout_milliseconds: 8000]}

• data_governance: OPTIONAL Describes the location of your feature flag and setting data within the ConfigCat CDN. This parameter needs to be in sync with your Data Governance preferences. Defaults to :global. More about Data Governance.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", data_governance: :eu_only]}

• default_user: OPTIONAL user object that will be used as fallback when there's no user parameter is passed to the getValue() method.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", default_user: User.new("test@test.com")]}

• flag_overrides: OPTIONAL Specify a data source to use for local flag overrides. The data source must implement the ConfigCat.OverrideDataSource protocol. ConfigCat.LocalFileDataSource and ConfigCat.LocalMapDataSource are provided for you to use.

• hooks: OPTIONAL Specify callback functions to be called when particular events are fired by the SDK. See ConfigCat.Hooks.

• http_proxy: OPTIONAL Specify this option if you need to use a proxy server to access your ConfigCat settings. You can provide a simple URL, like https://my_proxy.example.com or include authentication information, like https://user:password@my_proxy.example.com/.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", http_proxy: "https://my_proxy.example.com"]}

• name: OPTIONAL A unique identifier for this instance of ConfigCat. Defaults to ConfigCat. Must be provided if you need to run more than one instance of ConfigCat in the same application. If you provide a name, you must then pass that name to all of the API functions using the client option. See Multiple Instances below.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", name: :unique_name]}

  ConfigCat.get_value("setting", "default", client: :unique_name)

• offline: OPTIONAL # Indicates whether the SDK should be initialized in offline mode or not.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", offline: true]}

• read_timeout_milliseconds: OPTIONAL timeout for receiving an HTTP response from the socket, in milliseconds. Default is 5000.

  {ConfigCat, [sdk_key: "YOUR SDK KEY", read_timeout_milliseconds: 5000]}

Multiple Instances

If you need to run more than one instance of ConfigCat, there are two ways you can do it.

Module-Based

You can create a module that uses ConfigCat and then call the ConfigCat API functions on that module. This is the recommended option, as it makes the calling code a bit clearer and simpler.

You can pass any of the options listed above as arguments to use ConfigCat or specify them in your supervisor. Arguments specified by the supervisor take precedence over those provided to use ConfigCat.

# lib/my_app/first_flags.ex
defmodule MyApp.FirstFlags do
  use ConfigCat, sdk_key: "sdk_key_1"
end

# lib/my_app/second_flags.ex
defmodule MyApp.SecondFlags do
  use ConfigCat, sdk_key: "sdk_key_2"
end

# lib/my_app/application.ex
def start(_type, _args) do
  children = [
    # ... other children ...
    FirstFlags,
    SecondFlags,
  ]

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


# Calling code:
FirstFlags.get_value("someKey", "default value")
SecondFlags.get_value("otherKey", "other default")

Explicit Client

If you prefer not to use the module-based solution, you can instead add multiple ConfigCat children to your application's supervision tree. You will need to give ConfigCat a unique name option for each, as well as using Supervisor.child_spec/2 to provide a unique id for each instance.

When calling the ConfigCat API functions, you'll pass a client: keyword argument with the unique name you gave to that instance.

# lib/my_app/application.ex
def start(_type, _args) do
  children = [
    # ... other children ...
    Supervisor.child_spec({ConfigCat, [sdk_key: "sdk_key_1", name: :first]}, id: :config_cat_1),
    Supervisor.child_spec({ConfigCat, [sdk_key: "sdk_key_2", name: :second]}, id: :config_cat_2),
  ]

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

# Calling code:
ConfigCat.get_value("someKey", "default value", client: :first)
ConfigCat.get_value("otherKey", "other default", client: :second)

Use the API

Once ConfigCat has been started as part of your application's supervision tree, you can use its API to access your settings.

ConfigCat.get_value("isMyAwesomeFeatureEnabled", false)

By default, all of the public API functions will communicate with the default instance of the ConfigCat application.

If you are running multiple instances of ConfigCat, you must provide the client option to the functions, passing along the unique name you specified above.

ConfigCat.get_value("isMyAwesomeFeatureEnabled", false, client: :second)