ConfigCat (ConfigCat v2.0.0) View Source

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

If you need to run more than one instance of ConfigCat, you can add multiple ConfigCat children. 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.

# 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

Options

ConfigCat takes a number of other 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: OPTIONAL timeout for establishing a TCP or SSL connection, in milliseconds. Default is 8000.

    {ConfigCat, [sdk_key: "YOUR SDK KEY", connect_timeout: 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]}
  • 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.

  • 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.

    {ConfigCat, [sdk_key: "YOUR SDK KEY", name: :unique_name]}
    ConfigCat.get_value("setting", "default", client: :unique_name)
  • read_timeout: OPTIONAL timeout for receiving an HTTP response from the socket, in milliseconds. Default is 5000.

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

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)

Link to this section Summary

Types

Options that can be passed to all API functions.

Data Governance mode

Identifier of a specific instance of ConfigCat.

The name of a configuration setting.

An option that can be provided when starting ConfigCat.

The return value of the force_refresh/1 function.

The actual value of a configuration setting.

The name of a variation being tested.

Functions

Returns a specification to start this module under a supervisor.

Force a refresh of the configuration from ConfigCat's CDN.

Queries all settings keys in your configuration.

Fetches the values of all feature flags or settings from your configuration.

Retrieves a list of all variation ids from your configuration.

Fetches the name and value of the setting corresponding to a variation id.

Retrieves a setting value from your configuration.

Retrieves the variation id for a setting from your configuration.

Starts an instance of ConfigCat.

Link to this section Types

Specs

api_option() :: {:client, instance_id()}

Options that can be passed to all API functions.

Specs

data_governance() :: :eu_only | :global

Data Governance mode

More about Data Governance

Specs

instance_id() :: atom()

Identifier of a specific instance of ConfigCat.

Specs

The name of a configuration setting.

Specs

option() ::
  {:base_url, String.t()}
  | {:cache, module()}
  | {:cache_policy, ConfigCat.CachePolicy.t()}
  | {:connect_timeout, non_neg_integer()}
  | {:data_governance, data_governance()}
  | {:flag_overrides, ConfigCat.OverrideDataSource.t()}
  | {:http_proxy, String.t()}
  | {:name, instance_id()}
  | {:read_timeout, non_neg_integer()}
  | {:sdk_key, String.t()}

An option that can be provided when starting ConfigCat.

Specs

options() :: [option()]

Specs

refresh_result() :: :ok | {:error, term()}

The return value of the force_refresh/1 function.

Specs

value() :: ConfigCat.Config.value()

The actual value of a configuration setting.

Specs

variation_id() :: ConfigCat.Config.variation_id()

The name of a variation being tested.

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

force_refresh(options \\ [])

View Source

Specs

force_refresh([api_option()]) :: refresh_result()

Force a refresh of the configuration from ConfigCat's CDN.

Depending on the polling mode you're using, ConfigCat may automatically fetch your configuration during normal operation. Call this function to force a manual refresh when you want one.

If you are using manual polling mode (ConfigCat.CachePolicy.manual/0), this is the only way to fetch your configuration.

Returns :ok.

Options

  • client: If you are running multiple instances of ConfigCat, provide the client: :unique_name option, specifying the name you configured for the instance you want to access.
Link to this function

get_all_keys(options \\ [])

View Source

Specs

get_all_keys([api_option()]) :: [key()]

Queries all settings keys in your configuration.

Options

  • client: If you are running multiple instances of ConfigCat, provide the client: :unique_name option, specifying the name you configured for the instance you want to access.
Link to this function

get_all_values(user, options \\ [])

View Source

Specs

get_all_values(ConfigCat.User.t() | nil, [api_option()]) :: %{
  required(key()) => value()
}

Fetches the values of all feature flags or settings from your configuration.

To use ConfigCat's targeting feature, provide a ConfigCat.User struct containing the information used by the targeting rules.

Returns a map of all key value pairs.

Options

  • client: If you are running multiple instances of ConfigCat, provide the client: :unique_name option, specifying the name you configured for the instance you want to access.
Link to this function

get_all_variation_ids(user_or_options \\ [])

View Source

Specs

get_all_variation_ids(ConfigCat.User.t() | [api_option()]) :: [variation_id()]

See get_all_variation_ids/2.

Link to this function

get_all_variation_ids(user, options)

View Source

Specs

get_all_variation_ids(ConfigCat.User.t() | nil, [api_option()]) :: [
  variation_id()
]

Retrieves a list of all variation ids from your configuration.

To use ConfigCat's targeting feature, provide a ConfigCat.User struct containing the information used by the targeting rules.

Returns a list of all variation ids.

Options

  • client: If you are running multiple instances of ConfigCat, provide the client: :unique_name option, specifying the name you configured for the instance you want to access.
Link to this function

get_key_and_value(variation_id, options \\ [])

View Source

Specs

get_key_and_value(variation_id(), [api_option()]) :: {key(), value()} | nil

Fetches the name and value of the setting corresponding to a variation id.

Returns a tuple containing the setting name and value, or nil if an error occurs.

Options

  • client: If you are running multiple instances of ConfigCat, provide the client: :unique_name option, specifying the name you configured for the instance you want to access.
Link to this function

get_value(key, default_value, user_or_options \\ [])

View Source

Specs

get_value(key(), value(), ConfigCat.User.t() | [api_option()]) :: value()

See get_value/4.

Link to this function

get_value(key, default_value, user, options)

View Source

Specs

get_value(key(), value(), ConfigCat.User.t() | nil, [api_option()]) :: value()

Retrieves a setting value from your configuration.

Retrieves the setting named key from your configuration. To use ConfigCat's targeting feature, provide a ConfigCat.User struct containing the information used by the targeting rules.

Returns the value of the setting, or default_value if an error occurs.

Options

  • client: If you are running multiple instances of ConfigCat, provide the client: :unique_name option, specifying the name you configured for the instance you want to access.
Link to this function

get_variation_id(key, default_variation_id, user_or_options \\ [])

View Source

Specs

get_variation_id(key(), variation_id(), ConfigCat.User.t() | [api_option()]) ::
  variation_id()

See get_variation_id/4.

Link to this function

get_variation_id(key, default_variation_id, user, options)

View Source

Specs

get_variation_id(key(), variation_id(), ConfigCat.User.t() | nil, [api_option()]) ::
  variation_id()

Retrieves the variation id for a setting from your configuration.

Retrieves the setting named key from your configuration. To use ConfigCat's targeting feature, provide a ConfigCat.User struct containing the information used by the targeting rules.

Returns the variation id of the setting, or default_variation_id if an error occurs.

Options

  • client: If you are running multiple instances of ConfigCat, provide the client: :unique_name option, specifying the name you configured for the instance you want to access.

Specs

start_link(options()) :: Supervisor.on_start()

Starts an instance of ConfigCat.

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