初始化开发工具包

本文介绍如何在应用中初始化云眼灰度发布（特性标帜）AB实验 Swift SDK。

使用start方法初始化 Swift SDK 并实例化 Eyeofcloud 客户端类的实例，该实例公开 API 方法，如 Decide 方法。每个客户端对应于表示特定环境的项目状态的数据文件。数据文件可通过 EyeofcloudConfig 访问。

版本

SDK v3.1.0 及更高版本

描述

构造函数接受配置对象来配置云眼灰度发布（特性标帜）AB实验。

某些参数是可选的，因为 SDK 提供默认实现，但开发者可能希望为生产环境覆盖这些参数。例如，开发者可能希望设置错误处理程序和记录器来捕获问题，设置事件调度程序来管理网络调用，以及用户配置文件服务以确保粘性分桶。

参数

下表列出了start方法的必需参数和可选参数：

参数	类型	描述
(必选) sdk密钥	字符串	开发工具包密钥
记录器可选	OPTLogger	自定义记录器
事件调度程序可选	OPTEventDispatcher	自定义事件处理程序
用户配置文件服务可选	OTPUserProfileService	自定义用户配置文件服务
周期下载间隔可选	国际	定期后台数据文件下载的自定义间隔（以秒为单位）（默认值 = 10 * 60 秒）
默认日志级别 可选	优化日志级别	日志级别（默认值 = EyeofcloudLogLevel.info）
默认决定选项可选	数组	Array of EyeofcloudDecideOption enums.当使用此参数构造 Eyeofcloud 客户端时，它会设置默认的 decide 选项，这些选项将应用于在 Eyeofcloud 客户端的生命周期内进行的所有 Decide 调用。此外，还可以将选项传递给各个 Decide 方法（不会覆盖默认值）。 有关决定选项的详细信息，请参阅云眼决策选项。

返回

❗️

警告

我们目前支持每个 SDK 密钥一个并发实例。

实例化 Eyeofcloud 类的实例。

例子

在我们的 Swift SDK 中，您无需直接管理数据文件。SDK 包含一个数据文件管理器，该管理器支持数据文件轮询，以便在应用程序处于前台时定期自动更新数据文件。

要使用它：

1. 通过提供 SDK 密钥和可选配置设置来创建EyeofcloudClient。可以在全栈项目的设置>环境选项卡中找到 SDK 密钥。

2. 选择是同步还是异步启动客户端，并使用适当的start方法来实例化客户端。

Swift

// Build and config EyeofcloudClient 
eyeofcloud = EyeofcloudClient(sdkKey: "<Your_SDK_Key>") 
let user = eyeofcloud.createUserContext(userId: userId)          

// Synchronously initialize the client, then make a decision for a flag rule (such as an A/B test) do {     
            try eyeofcloud.start(datafile: datafileJSON)      
    let decision = user.decide(key: "flagKey")   
    let variationKey = decision.variationKey         
} catch {   
    // errors 
}    

// Or, instantiate it asynchronously with a callback 
eyeofcloud.start { result in     
        let decision = user.decide(key: "flagKey")   
    let variationKey = decision.variationKey    
}

目标-C

// Build and config EyeofcloudClient 
self.eyeofcloud = [[EyeofcloudClient alloc] initWithSdkKey:@"<Your_SDK_Key>"]; 
self.user = [eyeofcloud createUserContextWithUserId:userId attributes:attributes];     
// Synchronously initialize the client, then activate an experiment 
BOOL status = [self.eyeofcloud startWithDatafile:datafileJSON error:nil];  

EyeofcloudDecision *decision = [user decideWithKey:flagKey];  
NSString *variationKey = decision.variationKey;  

// Or, instantiate it asynchronously with a callback 
[self.eyeofcloud startWithCompletion:^(NSData *data, NSError *error) {   
    EyeofcloudDecision *decision = [user decideWithKey:flagKey];    
    NSString *variationKey = decision.variationKey; 
}];

请参阅的 斯威夫特示例：AppDelegate.swift .我们还提供 Objective-C 示例：AppDelegate.m .

使用同步或异步初始化

对于何时实例化 Eyeofcloud 客户端，您有两种选择：同步和异步。这两种方法之间的_行为_区别在于，应用程序是否在初始化期间对云眼灰度发布（特性标帜）AB实验服务器执行 ping 操作以获取新的数据文件。这两种方法之间的_功能_区别在于你的应用是优先考虑准确性还是速度。

同步初始化

同步方法优先考虑速度而不是精度。应用程序不会在每次初始化 Eyeofcloud 客户端时尝试下载新的数据文件，而是使用数据文件的本地变体。可以从以前的网络请求缓存此本地数据文件。

同步初始化客户机时，Eyeofcloud 管理器首先搜索高速缓存的数据文件。如果可用，管理器将使用它来完成客户端初始化。如果管理器找不到缓存的数据文件，管理器将搜索捆绑的数据文件。如果管理器找到捆绑的数据文件，它将使用该数据文件完成客户机初始化。如果管理器找不到捆绑的数据文件，则管理器无法初始化客户端。

要同步初始化对象，请调用EyeofcloudClient``eyeofcloudClient.start(datafile:datafile)。

🚧 重要

传递的数据文件必须与初始化 Eyeofcloud 管理器时提供的项目 ID 相同。

异步初始化

异步方法优先考虑准确性而不是速度。在初始化期间，应用会从 CDN 服务器请求最新的数据文件。请求最新的数据文件可确保应用始终使用最新的项目设置，但这也意味着应用无法实例化客户端，直到它下载新的数据文件、发现数据文件未更改或请求超时。这个过程需要时间。

异步初始化客户端与同步初始化类似，只是管理器将首先尝试下载最新的数据文件。此网络活动是导致异步初始化需要更长的时间才能完成的原因。

如果网络请求返回错误（例如，当网络连接不可靠时），或者如果管理器发现缓存的数据文件与最新的数据文件相同，那么管理器将使用同步方法。如果管理中心发现数据文件已更新，并且现在与高速缓存的数据文件不同，那么管理中心将下载新的数据文件并使用它来初始化客户机。

若要异步初始化 EyeofcloudClient对象，请调用eyeofcloudClient.start(completion:)并向其传递回调函数。

🚧 重要

传递的数据文件必须与初始化 Eyeofcloud 管理器时提供的项目 ID 相同。

配置数据文件轮询

在初始化期间，管理器尝试从 CDN 服务器拉取最新的数据文件。在此之后，Eyeofcloud 管理器可以按照您在初始化期间设置的时间间隔定期检查并拉取新数据文件。检查和下载新数据文件的过程称为_数据文件轮询_。

默认情况下，数据文件轮询处于禁用状态，因此客户端仅在初始化期间检查新的数据文件。要启用轮询，请设置非零间隔值。此值是管理器在数据文件轮询尝试之间等待的秒数。

Swift

// Datafile update interval can be configured when the SDK is configured 
// Background datafile update is disabled if periodicDownloadInterval is zero 
eyeofcloud = EyeofcloudClient(sdkKey: "<Your_SDK_Key>",
                                periodicDownloadInterval: 5*60) 
// every 5 minutes

目标-C

// Datafile update interval can be configured when the SDK is configured 
// Background datafile update is disabled if periodicDownloadInterval is zero 
self.eyeofcloud = [[EyeofcloudClient alloc]  initWithSdkKey:@"<Your_SDK_Key>"                     
    logger:nil                     
    eventDispatcher:nil                     
    userProfileService:nil                     
    periodicDownloadInterval:5*60                     
    defaultLogLevel:EyeofcloudLogLevelInfo];

使用说明

• 应用打开时的最小轮询间隔为 2 分钟。如果指定的轮询间隔短于最小值，SDK 会自动将间隔重置为 2 分钟。
• Eyeofcloud 管理器仅在 SDK 处于活动状态且应用程序在 iOS/tvOS 上运行时检查新数据文件。必须使用应用程序委托并调用数据文件管理器下载在 iOS 中配置后台更新。
• 如果启用了数据文件轮询，则 Swift SDK 会在检测到新数据文件时自动更新，以确保您始终使用最新的数据文件。要在项目更新时收到通知，请通过数据文件更改通知侦听器注册数据文件更改。Swift 演示应用程序展示了一个示例，其中我们基于新的数据文件重新运行“已启用功能”方法。
• 如果希望在应用程序进入前台时更新数据文件，则可以执行以下操作：
  1. 设置周期下载间隔 = 0
  2. 只需从前台调用 start 即可：

Swift

func applicationWillEnterForeground(_ application: UIApplication) {
         eyeofcloud.start { result in             
            switch result {             
            case .failure(let error):                 
                print("Eyeofcloud SDK initialization failed: \(error)")             
            case .success:                 
                print("Eyeofcloud SDK initialized successfully!")                 
                // retest your features or experiments?             
            }                                      
            
            self.startWithRootViewController()         
        }     
    }

启用捆绑数据文件

当客户在安装或更新应用程序后首次打开应用程序时，经理会尝试从 Eyeofcloud 的 CDN 中提取最新的数据文件。如果应用无法联系服务器，则管理器可以替换您在创建应用时包含（捆绑）的数据文件。

通过在应用程序中捆绑数据文件，可以确保 Eyeofcloud 管理器无需等待 CDN 的响应即可初始化。这样可以防止网络连接不良导致应用在加载时挂起或崩溃。

数据文件捆绑同时适用于同步和异步初始化，因为恢复到捆绑的数据文件发生在 Eyeofcloud 管理器初始化期间，在客户端实例化之前。

Swift

eyeofcloud = EyeofcloudClient(sdkKey: "<Your_SDK_Key>")  

do {     
    
        let localDatafilePath = Bundle.main.path(forResource: “datafileName”, ofType: "json")!     
        let datafileJSON = try String(contentsOfFile: localDatafilePath, encoding: .utf8)     
        try eyeofcloud.start(datafile: datafileJSON)          
        
        // Eyeofcloud SDK initialized successfully 
} catch {     
    // Eyeofcloud SDK initiliazation failed 
}

目标-C

self.eyeofcloud = [[EyeofcloudClient alloc] initWithSdkKey:@"<Your_SDK_Key>"];

NSString *filePath = [[NSBundle mainBundle] pathForResource:@“fileName” ofType:@"json"] 
NSString *datafileJSON = [NSString stringWithContentsOfFile:filePath encoding:NSUTF8StringEncoding error:nil];  

BOOL status = [self.eyeofcloud startWithDatafile:datafileJSON error:nil];

更多示例代码

Swift

// Here are sample codes for synchronous and asynchronous SDK initializations with multiple options  
// [Synchronous]          

// [S1] Synchronous initialization 
//      1. SDK is initialized instantly with a cached (or bundled) datafile 
//      2. A new datafile can be downloaded in background and cached after the SDK is initialized. 
//         The cached datafile will be used only when the SDK re-starts in the next session.  
eyeofcloud = EyeofcloudClient(sdkKey: "<Your_SDK_Key>") 
try? eyeofcloud.start(datafile: localDatafile) 
user = eyeofcloud.createUserContext(userId: userId) 
let decision = user.decide(key: "flagKey") 
let variationKey = decision.variationKey                  

// [S2] Synchronous initialization 
//      1. SDK is initialized instantly with a cached (or bundled) datafile 
//      2. A new datafile can be downloaded in background and cached after the SDK is initialized. 
//         The cached datafile is used immediately to update the SDK project config.          

eyeofcloud = EyeofcloudClient(sdkKey: "<Your_SDK_Key>") 
try? eyeofcloud.start(datafile: localDatafile,                               
                                    doUpdateConfigOnNewDatafile: true) 
user = eyeofcloud.createUserContext(userId: userId) 
let decision = user.decide(key: flagKey) 
let variationKey = decision.variationKey                  

// [S3] Synchronous initialization 
//      1. SDK is initialized instantly with a cached (or bundled) datafile 
//      2. A new datafile can be downloaded in background and cached after the SDK is initialized. 
//         The cached datafile is used immediately to update the SDK project config. 
//      3. Polling datafile periodically. 
//         The cached datafile is used immediately to update the SDK project config.          

eyeofcloud = EyeofcloudClient(sdkKey: "<Your_SDK_Key>",
                                       periodicDownloadInterval: 60) 
try? eyeofcloud.start(datafile: localDatafile) 
user = eyeofcloud.createUserContext(userId: userId) 
let decision = user.decide(key: flagKey) 
let variationKey = decision.variationKey                  

// [Asynchronous]          

// [A1] Asynchronous initialization 
//      1. A datafile is downloaded from the server and the SDK is initialized with the datafile  
eyeofcloud = EyeofcloudClient(sdkKey: "<Your_SDK_Key>") 
eyeofcloud.start { result in
                 user = eyeofcloud.createUserContext(userId: userId)         
                 let decision = user.decide(key: flagKey)         
                 let variationKey = decision.variationKey         
}          

// [A2] Asynchronous initialization 
//      1. A datafile is downloaded from the server and the SDK is initialized with the datafile 
//      2. Polling datafile periodically. 
//         The cached datafile is used immediately to update the SDK project config.          

eyeofcloud = EyeofcloudClient(sdkKey: "<Your_SDK_Key>",
                                       periodicDownloadInterval: 60) 
                                       
eyeofcloud.start { result in         
                user = eyeofcloud.createUserContext(userId: userId)         
                let decision = user.decide(key: flagKey)         
                let variationKey = decision.variationKey         
}

源文件

包含 Swift 实现的语言/平台源文件位于 EyeofcloudClient.swift。