Swiftpack.co - Package - configcat/swift-sdk

ConfigCat Swift SDK

ConfigCat is a cloud based configuration as a service. It integrates with your apps, backends, websites, and other programs, so you can configure them through this website even after they are deployed.

Build Status Coverage Status CocoaPods Carthage compatible Supported Platforms

Getting started

1. Add the package to your project


Add the following to your Podfile:

target '<YOUR TARGET>' do
pod 'ConfigCat'

Then, run the following command to install your dependencies:

pod install


Add the following to your Cartfile:

github "configcat/swift-sdk"

Then, run the carthage update command and then follow the Carthage integration steps to link the framework with your project.

2. Get your Api Key from ConfigCat.com portal YourConnectionUrl

3. Import the ConfigCat module

import ConfigCat

4. Create a ConfigCatClient instance

let client = ConfigCatClient(apiKey: "<PLACE-YOUR-API-KEY-HERE>")

5. (Optional) Prepare a User object for rollout calculation

let user = User(identifier: "<PLACE-YOUR-USER-IDENTIFIER-HERE>")

6. Get your config value

let isMyAwesomeFeatureEnabled = client.getValue(for: "key-of-my-awesome-feature", defaultValue: false, user: user)
if(isMyAwesomeFeatureEnabled) {
    //show your awesome feature to the world!

Or use the async APIs:

client.getValueAsync(for: "key-of-my-awesome-feature", defaultValue: false, completion: { isMyAwesomeFeatureEnabled in
        if(isMyAwesomeFeatureEnabled) {
            //show your awesome feature to the world!

User object

Percentage and targeted rollouts are calculated by the user object you can optionally pass to the configuration requests. The user object must be created with a mandatory identifier parameter which should uniquely identify each user:

let user = User(identifier: "<PLACE-YOUR-USER-IDENTIFIER-HERE>" /* mandatory */)

But you can also set other custom attributes if you'd like to calculate the rollout based on them:

let user = User(identifier: "<PLACE-YOUR-USER-IDENTIFIER-HERE>", // mandatory
    email: "simple@but.awesome.com", 
    country: "Awesomnia", 
    custom: ["Subscription":"Free", "Role":"Knight of Awesomnia"]])


Refresh policies

The internal caching control and the communication between the client and ConfigCat are managed through a refresh policy. There are 3 predefined implementations built in the library.

1. Auto polling policy (default)

This policy fetches the latest configuration and updates the cache repeatedly.

You have the option to configure the polling interval and an onConfigChanged closure that will be notified when a new configuration is fetched. The policy calls the given method only, when the new configuration is differs from the cached one.

let factory = { (cache: ConfigCache, fetcher: ConfigFetcher) -> RefreshPolicy in
    AutoPollingPolicy(cache: cache,
                      fetcher: fetcher,
                      autoPollIntervalInSeconds: 30,
                      onConfigChanged: { (config, parser) in
                          let isMyAwesomeFeatureEnabled: String = try! parser.parseValue(for: "key-of-my-awesome-feature", json: configString)
                          if(isMyAwesomeFeatureEnabled) {
                              //show your awesome feature to the world!
let client = ConfigCatClient(apiKey: "<PLACE-YOUR-API-KEY-HERE>", policyFactory: factory)

2. Expiring cache policy

This policy uses an expiring cache to maintain the internally stored configuration.

Cache refresh interval

You can define the refresh rate of the cache in seconds, after the initial cached value is set this value will be used to determine how much time must pass before initiating a new configuration fetch request through the ConfigFetcher.

Async / Sync refresh

You can define how do you want to handle the expiration of the cached configuration. If you choose asynchronous refresh then when a request is being made on the cache while it's expired, the previous value will be returned immediately until the fetching of the new configuration is completed.

let factory = { (cache: ConfigCache, fetcher: ConfigFetcher) -> RefreshPolicy in
    ExpiringCachePolicy(cache: cache,
                        fetcher: fetcher,
                        cacheRefreshIntervalInSeconds: 30,
                        useAsyncRefresh = true)
let client = ConfigCatClient(apiKey: "<PLACE-YOUR-API-KEY-HERE>", policyFactory: factory)

3. Manual polling policy

With this policy every new configuration request on the ConfigCatClient will trigger a new fetch over HTTP.

let factory = { (cache: ConfigCache, fetcher: ConfigFetcher) -> RefreshPolicy in
    ManualPollingPolicy(cache, fetcher))
let client = ConfigCatClient(apiKey: "<PLACE-YOUR-API-KEY-HERE>", policyFactory: factory)

Custom Policy

You can also implement your custom refresh policy by extending the RefreshPolicy open class.

public class MyCustomPolicy : RefreshPolicy {
    public required init(cache: ConfigCache, fetcher: ConfigFetcher) {
        super.init(cache: cache, fetcher: fetcher)
    public override func getConfiguration() -> AsyncResult<String> {
        // this method will be called when the configuration is requested from the ConfigCat client.
        // you can access the config fetcher through the super.fetcher and the internal cache via super.cache

The AsyncResult is an internal type used to signal back to the caller about the completion of a given task like Futures.

Then you can simply inject your custom policy implementation into the ConfigCat client:

let factory = { (cache: ConfigCache, fetcher: ConfigFetcher) -> RefreshPolicy in
    MyCustomPolicy(cache, fetcher))
let client = ConfigCatClient(apiKey: "<PLACE-YOUR-API-KEY-HERE>", policyFactory: factory)

Custom Cache

You have the option to inject your custom cache implementation into the client. All you have to do is to inherit from the ConfigCache open class:

public class MyCustomCache : ConfigCache {
    open override func read() throws -> String {
        // here you have to return with the cached value
        // you can access the latest cached value in case 
        // of a failure like: super.inMemoryValue
    open override func write(value: String) throws {
        // here you have to store the new value in the cache

Then use your custom cache implementation:

let client = ConfigCatClient(apiKey: "<PLACE-YOUR-API-KEY-HERE>", configCache: MyCustomCache())

Maximum wait time for synchronous calls

You have the option to set a timeout value for the synchronous methods of the library (getValue(), forceRefresh()) which means when a sync call takes longer than the timeout value, it'll return with the default.

let client = ConfigCatClient(apiKey: "<PLACE-YOUR-API-KEY-HERE>", maxWaitTimeForSyncCallsInSeconds: 5)

Force refresh

Any time you want to refresh the cached configuration with the latest one, you can call the forceRefresh() method of the library, which will initiate a new fetch and will update the local cache.



Stars: 0
Help us keep the lights on


Used By

Total: 0


2.1.1 - Oct 16, 2018

2.1.0 - Oct 14, 2018

2.0.0 - Oct 7, 2018

1.0.3 - May 7, 2018

1.0.2 - May 4, 2018