View Source ConfigCat (ConfigCat v4.0.2)
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 theConfigCat.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 byConfigCat
. Defaults to auto-polling mode with a 60 second poll interval. You can specify a different polling mode or polling interval usingConfigCat.CachePolicy.auto/1
,ConfigCat.CachePolicy.lazy/1
, orConfigCat.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 theConfigCat.OverrideDataSource
protocol.ConfigCat.LocalFileDataSource
andConfigCat.LocalMapDataSource
are provided for you to use.hooks
: OPTIONAL Specify callback functions to be called when particular events are fired by the SDK. SeeConfigCat.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, likehttps://my_proxy.example.com
or include authentication information, likehttps://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 ofConfigCat
. Defaults toConfigCat
. Must be provided if you need to run more than one instance ofConfigCat
in the same application. If you provide aname
, you must then pass that name to all of the API functions using theclient
option. SeeMultiple 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 use
s 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)
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.
The return value of the force_refresh/1
function.
The actual value of a configuration setting.
The name of a variation being tested.
Functions
Builds a child specification to use in a Supervisor.
Clears the default user.
Force a refresh of the configuration from ConfigCat's CDN.
Queries all settings keys in your configuration.
Fetches the values and evaluation details of all feature flags and settings.
Fetches the values of all feature flags or settings from your configuration.
Fetches the name and value of the setting corresponding to a variation id.
Retrieves a setting value from your configuration.
Fetches the value and evaluation details of a feature flag or setting.
Return the current hook callbacks.
Returns true
when the SDK is configured not to initiate HTTP requests, otherwise false
.
Sets the default user.
Configures the SDK to not initiate HTTP requests and work only from its cache.
Configures the SDK to allow HTTP requests.
Types
@type api_option() :: {:client, instance_id()}
Options that can be passed to all API functions.
@type data_governance() :: :eu_only | :global
Data Governance mode
@type instance_id() :: atom()
Identifier of a specific instance of ConfigCat
.
@type key() :: ConfigCat.Config.key()
The name of a configuration setting.
@type option() :: {:base_url, String.t()} | {:cache, module()} | {:cache_policy, ConfigCat.CachePolicy.t()} | {:connect_timeout_milliseconds, non_neg_integer()} | {:data_governance, data_governance()} | {:default_user, ConfigCat.User.t()} | {:flag_overrides, ConfigCat.OverrideDataSource.t()} | {:hooks, [ConfigCat.Hooks.option()]} | {:http_proxy, String.t()} | {:name, instance_id()} | {:offline, boolean()} | {:read_timeout_milliseconds, non_neg_integer()} | {:sdk_key, String.t()}
An option that can be provided when starting ConfigCat
.
@type options() :: [option()]
@type refresh_result() :: :ok | {:error, String.t()}
The return value of the force_refresh/1
function.
@type value() :: ConfigCat.Config.value()
The actual value of a configuration setting.
@type variation_id() :: ConfigCat.Config.variation_id()
The name of a variation being tested.
Functions
@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 ConfigCat
to its supervision tree.
@spec clear_default_user([api_option()]) :: :ok
Clears the default user.
Returns :ok
.
Options
client
: If you are running multiple instances ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec 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 ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec get_all_keys([api_option()]) :: [key()]
Queries all settings keys in your configuration.
Options
client
: If you are running multiple instances ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec get_all_value_details(ConfigCat.User.t() | [api_option()]) :: [ ConfigCat.EvaluationDetails.t() ]
@spec get_all_value_details(ConfigCat.User.t() | nil, [api_option()]) :: [ ConfigCat.EvaluationDetails.t() ]
Fetches the values and evaluation details of all feature flags and settings.
To use ConfigCat's targeting
feature, provide a ConfigCat.User
struct containing the information used by
the targeting rules.
Returns evaluation details for all settings and feature flags, including their
values. If an error occurs while performing the evaluation, it will be
captured in the :error
field of the individual ConfigCat.EvaluationDetails
structs.
Options
client
: If you are running multiple instances ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec 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 ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec 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 ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec get_value(key(), value(), ConfigCat.User.t() | [api_option()]) :: value()
See get_value/4
.
@spec 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 ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec get_value_details(key(), value(), ConfigCat.User.t() | [api_option()]) :: ConfigCat.EvaluationDetails.t()
See get_value_details/4
.
@spec get_value_details(key(), value(), ConfigCat.User.t() | nil, [api_option()]) :: ConfigCat.EvaluationDetails.t()
Fetches the value and evaluation details of a feature flag or setting.
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 evaluation details for the setting, including the value. If an
error occurs while performing the evaluation, it will be captured in the
:error
field of the ConfigCat.EvaluationDetails
struct.
Options
client
: If you are running multiple instances ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec hooks([api_option()]) :: ConfigCat.Hooks.t()
Return the current hook callbacks.
Options
client
: If you are running multiple instances ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec offline?([api_option()]) :: boolean()
Returns true
when the SDK is configured not to initiate HTTP requests, otherwise false
.
Options
client
: If you are running multiple instances ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec set_default_user(ConfigCat.User.t(), [api_option()]) :: :ok
Sets the default user.
Returns :ok
.
Options
client
: If you are running multiple instances ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec set_offline([api_option()]) :: :ok
Configures the SDK to not initiate HTTP requests and work only from its cache.
Returns :ok
.
Options
client
: If you are running multiple instances ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
@spec set_online([api_option()]) :: :ok
Configures the SDK to allow HTTP requests.
Returns :ok
.
Options
client
: If you are running multiple instances ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.