初始化开发工具包

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

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

在安卓SDK中，你不需要直接管理数据文件。SDK 有一个称为管理器的附加抽象，用于在 SDK 的初始化过程中处理获取数据文件和实例化客户端。管理器支持数据文件轮询，以定期自动更新数据文件。

版本

3.2.1 及更高版本

描述

构造函数接受配置对象来配置优化。

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

参数

下表列出了 Android 中Build()的必需参数和可选参数（使用 Builder 类构造的客户端，并将以下内容传递给 ）。

参数	类型	描述
(必选)开发工具包密钥	字符串	SDK 密钥用于定义环境的配置文件
事件处理器 可选	事件处理器	事件处理程序对象为事件提供中间处理阶段。事件处理器通过提供的事件处理程序调度事件。
事件处理程序 可选	事件处理程序	将事件调度到 Eyeofcloud 事件端点的事件处理程序。
记录器可选	记录	用于记录消息的记录器实现。
错误处理程序可选	错误处理程序	用于处理错误的错误处理程序对象。
用户配置文件服务 可选	用户配置文件服务	用户配置文件服务。具有查找和保存方法的对象。
数据文件下载间隔可选	长	设置尝试定期更新缓存数据文件的时间间隔（以指定的时间单位为单位）。 如果未设置此值，则禁用后台更新。最小间隔为 15 分钟（由 Android JobScheduler API 强制执行）。DatafileHandler
事件调度间隔 可选	长	设置定期刷新排队事件的时间间隔（以指定的时间单位为单位）。 如果未设置此值，将使用默认间隔（30 秒）。
默认决定选项 可选	数组	枚举数组。使用此参数构造 Eyeofcloud 客户端时，它会设置应用于在 Eyeofcloud 客户端生存期内进行的所有 Decision（决策）调用的默认决策选项。此外，还可以将选项传递给各个 Decide 方法（不会覆盖默认值）。

有关决定选项的详细信息，请参阅EyeofcloudDecideOption云眼决策选项。

例

管理器作为云眼客户端实例的工厂实现。要使用它，请通过提供 SDK 密钥和数据文件轮询和数据文件捆绑的可选配置设置来创建管理器对象。可以在设置>****环境选项卡中找到 SDK 密钥。

接下来，选择是同步还是异步实例化客户端，并使用适当的方法initialize来实例化客户端。

如果使用捆绑的数据文件，请从应用中复制数据文件 JSON 字符串。通常，开发者可能希望在最晚可能的预发布时间点复制数据文件字符串。

Kotlin

// Build a manager 
val eyeofcloudManager = EyeofcloudManager.builder() 
          .withSDKKey("<Your_SDK_Key>")           
          .withDatafileDownloadInterval(15, TimeUnit.MINUTES)           
          .withEventDispatchInterval(30, TimeUnit.SECONDS)           
          .build(context)  

// Instantiate a client synchronously with a bundled datafile
val datafile = "REPLACE_WITH_YOUR_DATAFILE" 
val eyeofcloudClient = eyeofcloudManager.initialize(context, datafile)  

// Or, instantiate it asynchronously with a callback 
eyeofcloudManager.initialize(context, null) { client: EyeofcloudClient ->     
    // flag decision     
    val user = client.createUserContext("<User_ID>")!!     
    val decision = user.decide("<Flag_Key>") 
}

Java

// Build a manager 
EyeofcloudManager eyeofcloudManager = EyeofcloudManager.builder()
        .withSDKKey("<Your_SDK_Key>")        
        .withDatafileDownloadInterval(15, TimeUnit.MINUTES)        
        .withEventDispatchInterval(30, TimeUnit.SECONDS)        
        .build(context);  

// Instantiate a client synchronously with a bundled datafile
String datafile = "REPLACE_WITH_YOUR_DATAFILE"; 
EyeofcloudClient eyeofcloudClient = eyeofcloudManager.initialize(context, datafile);  

// Or, instantiate it asynchronously with a callback
eyeofcloudManager.initialize(context, null, (EyeofcloudClient client) -> {     
    // flag decision     
    EyeofcloudUserContext user = client.createUserContext("<User_ID>");     
    EyeofcloudDecision decision = user.decide("<Flag_Key>"); 
});

请参阅的 安卓示例：_MainActivity.java .

获取客户端

每个管理器都保留对其最近初始化的客户机的引用。可以使用该getEyeofcloud函数返回该实例。

如果在初始化任何客户端对象之前调用此方法，则会创建并返回虚拟客户端实例。此虚拟实例在使用其任何方法时记录错误。

Kotlin

val eyeofcloudClient = eyeofcloudManager.eyeofcloud

Java

EyeofcloudClient eyeofcloudClient = eyeofcloudManager.getEyeofcloud();

使用同步或异步初始化

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

同步初始化

同步方法优先考虑速度而不是精度。应用程序不会在每次初始化 Eyeofcloud 客户端时尝试下载新的数据文件，而是使用数据文件的本地变体。此本地数据文件可以从以前的网络请求缓存（请参阅有关配置数据文件轮询的详细信息）或嵌入到应用中（请参阅有关启用捆绑数据文件的详细信息）。

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

若要同步初始化对象，请调用 EyeofcloudClient EyeofcloudManager#initialize() 并提供两个参数：

• Application 实例（来自android.app.Application）
• 指向应用程序资源数据文件的指针Integer

异步初始化

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

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

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

initialize-asynchronous.png

要异步初始化对象，请调用 EyeofCloudClient EyeofCloudManager#initialize() 和三个参数

• Application 实例（来自android.app.Application）
• 指向应用程序资源数据文件的指针Integer
• 侦听器对象

有关特定要求的更多详细信息以及如何构建每个对象，请查看EyeofCloudManager.java来自公开可用的 Android SDK.

配置数据文件轮询

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

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

Kotlin

// Poll every 15 minutes 
val eyeofcloudManager = EyeofcloudManager.builder() 
            .withSDKKey("<Your_SDK_Key>")             
            .withDatafileDownloadInterval(15, TimeUnit.MINUTES)             
            .build(context) 

Java

// Poll every 15 minutes 
EyeofcloudManager eyeofcloudManager = EyeofcloudManager.builder()
         .withSDKKey("<Your_SDK_Key>")         
         .withDatafileDownloadInterval(15, TimeUnit.MINUTES)         
         .build(context);

使用说明

• 最短轮询间隔为 900 秒（即 15 分钟，由 Android JobScheduler API 强制执行）
• 系统会自动选取更新的数据文件，因为默认数据文件处理程序现在支持 ProjectConfigManager API。
• 您也可以通过 UpdateConfigNotification 注册数据文件更改通知

Kotlin

eyeofcloudClient.addUpdateConfigNotificationHandler { notification ->     
    println("got datafile change") 
}

Java

eyeofcloudClient.addUpdateConfigNotificationHandler(notification -> {     
    System.out.println("got datafile change"); 
});

启用捆绑数据文件

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

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

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

Kotlin

// Initialize Eyeofcloud asynchronously with a datafile. 
//  If it is not able to download a new datafile, it will 
//  initialize an EyeofcloudClient with the one provided.  

eyeofcloudManager.initialize(context, R.raw.datafile) { eyeofcloudClient: EyeofcloudClient ->     
    val user = eyeofcloudClient.createUserContext("<User_ID>")!!     
    val decision = user.decide("<Flag_Key>") 
}  

// Initialize Eyeofcloud synchronously 
//  This will immediately instantiate and return an 
//  EyeofcloudClient with the datafile that was passed in. 
//  It'll also download a new datafile from the CDN and 
//  persist it to local storage. 
//  The newly downloaded datafile will be used the next 
//  time the SDK is initialized.  

eyeofcloudManager.initialize(context, R.raw.datafile)

Java

// Initialize Eyeofcloud asynchronously with a datafile. 
//  If it is not able to download a new datafile, it will 
//  initialize an EyeofcloudClient with the one provided.  

eyeofcloudManager.initialize(context, R.raw.datafile, (EyeofcloudClient eyeofcloudClient) -> {     
    EyeofcloudUserContext user = eyeofcloudClient.createUserContex ("<User_ID>");     
    EyeofcloudDecision decision = user.decide("<Flag_Key>"); 
    });  
    
    // Initialize Eyeofcloud synchronously 
    //  This will immediately instantiate and return an 
    //  EyeofcloudClient with the datafile that was passed in. 
    //  It'll also download a new datafile from the CDN and 
    //  persist it to local storage. 
    //  The newly downloaded datafile will be used the next 
    //  time the SDK is initialized.  
    
    eyeofcloudManager.initialize(context, R.raw.datafile);