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 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
: 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 theConfigCat.OverrideDataSource
protocol.ConfigCat.LocalFileDataSource
andConfigCat.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, 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.{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.
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
Specs
instance_id() :: atom()
Identifier of a specific instance of ConfigCat
.
Specs
key() :: ConfigCat.Config.key()
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
.
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 ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
Specs
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.
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 ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
Specs
get_all_variation_ids(ConfigCat.User.t() | [api_option()]) :: [variation_id()]
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 ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
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 ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
Specs
get_value(key(), value(), ConfigCat.User.t() | [api_option()]) :: value()
See get_value/4
.
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 ofConfigCat
, provide theclient: :unique_name
option, specifying the name you configured for the instance you want to access.
get_variation_id(key, default_variation_id, user_or_options \\ [])
View SourceSpecs
get_variation_id(key(), variation_id(), ConfigCat.User.t() | [api_option()]) :: variation_id()
See get_variation_id/4
.
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 ofConfigCat
, provide theclient: :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.