Java 开发工具包快速入门

云眼2023年5月11日大约 15 分钟

Java 开发工具包快速入门

欢迎阅读云眼灰度标帜(Feature Flag)AB实验 Android SDK 的快速入门指南。

按照本指南中的步骤创建灰度标帜(Feature Flag)、推出标帜传递，并使用简单的命令行应用程序运行 A/B 测试。

第一部分：创建示例应用

1. 获取免费帐户

需要一个云眼帐户才能遵循本指南。如果没有帐户，可以注册一个免费帐户。如果已有帐户，请导航到启用了标帜的项目。

2. 获取开发工具包密钥

要在云眼项目中查找开发工具包密钥，请执行以下操作：

转到“设置”>“主环境”。
复制并保存主环境的 SDK 密钥。

📘 注意
每个环境都有自己的开发工具包密钥。

3. 复制示例代码

要试用 SDK，请执行以下操作：

在 Android Studio 中，创建一个名为eyeofcloud_java_quickstart的新项目。
安装云眼灰度标帜(Feature Flag)AB实验 Android SDK。
在新项目下创建libs文件夹以存放所需依赖包
在build.gradle依赖项中，使用本地提供的SDK依赖包：

包管理控制台

dependencies {
    // Use local packages
    implementation fileTree(dir: 'libs', include: ['*.aar','*.jar'], exclude:[])
    api "org.slf4j:slf4j-api:1.7.30"

    implementation 'androidx.appcompat:appcompat:1.4.1'
    implementation 'com.google.android.material:material:1.5.0'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.3'
    implementation "androidx.work:work-runtime:2.7.1"
    implementation 'com.google.code.gson:gson:2.10.1'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'androidx.test.ext:junit:1.1.3'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0'
}

Android SDK完整的源代码托管在GitHub上。

在app/src/mian/res新建一个目录raw,在其中新创建一个文件datafile.json，并将以下代码粘贴进去

{
  "accountId": "1000033",
  "anonymizeIP": true,
  "attributes": [],
  "audiences": [],
  "botFiltering": false,
  "environmentKey": "Production",
  "events": [
    {
      "experimentIds": [
        "1000226"
      ],
      "id": "63",
      "key": "sample_conversion"
    }
  ],
  "experiments": [
    {
      "audienceConditions": [],
      "audienceIds": [],
      "forcedVariations": {},
      "id": "1000226",
      "key": "decide_demo_experiment",
      "layerId": "234",
      "status": "Running",
      "trafficAllocation": [
        {
          "endOfRange": 5000,
          "entityId": "503"
        },
        {
          "endOfRange": 10000,
          "entityId": "504"
        }
      ],
      "variations": [
        {
          "featureEnabled": true,
          "id": "503",
          "key": "variation_a",
          "variables": [
            {
              "id": "207",
              "value": "true"
            }
          ]
        },
        {
          "featureEnabled": true,
          "id": "504",
          "key": "variation_b",
          "variables": [
            {
              "id": "207",
              "value": "true"
            }
          ]
        }
      ]
    }
  ],
  "featureFlags": [
    {
      "experimentIds": [
        "1000226"
      ],
      "id": "86",
      "key": "decide_demo",
      "rolloutId": "rollout-86-115",
      "variables": [
        {
          "defaultValue": "true",
          "id": "207",
          "key": "boolean_variable",
          "type": "boolean"
        }
      ]
    }
  ],
  "groups": [],
  "integrations": [],
  "projectId": "1000249",
  "revision": "10",
  "rollouts": [
    {
      "experiments": [
        {
          "audienceConditions": [],
          "audienceIds": [],
          "forcedVariations": {},
          "id": "default-rollout-86-115",
          "key": "default-rollout-86-115",
          "layerId": "rollout-86-115",
          "status": "Running",
          "trafficAllocation": [
            {
              "endOfRange": 10000,
              "entityId": "268"
            }
          ],
          "variations": [
            {
              "featureEnabled": true,
              "id": "268",
              "key": "off",
              "variables": [
                {
                  "id": "207",
                  "value": "true"
                }
              ]
            }
          ]
        }
      ],
      "id": "rollout-86-115"
    }
  ],
  "sdkKey": "1000249_e395d80182db07ae",
  "sendFlagDecisions": false,
  "typedAudiences": [],
  "variables": [],
  "version": "4"
}

将以下代码示例复制到控制台应用的 MainActivity.java 文件中。
将<Your_SDK_Key>替换为在上一步中找到的 SDK 密钥。

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;

import com.eyeofcloud.ab.EyeofcloudUserContext;
import com.eyeofcloud.ab.android.sdk.EyeofcloudClient;
import com.eyeofcloud.ab.android.sdk.EyeofcloudManager;
import com.eyeofcloud.ab.android.shared.DatafileConfig;
import com.eyeofcloud.ab.android.shared.WorkerScheduler;
import com.eyeofcloud.ab.event.internal.EventFactory;
import com.eyeofcloud.ab.eyeofclouddecision.EyeofcloudDecision;

import java.util.Random;
import java.util.concurrent.TimeUnit;

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

//        initEyeofcloud();
        // change datafileHost
        DatafileConfig.defaultHost = "https://cdn.eyeofcloud.com";
        // change eventHost
        EventFactory.EVENT_ENDPOINT = "https://event.eyeofcloud.com/v1/events";

        EyeofcloudManager eyeofcloudManager = EyeofcloudManager.builder()
                .withEventDispatchInterval(1L, TimeUnit.SECONDS)
                .withDatafileDownloadInterval(15, TimeUnit.MINUTES)
                .withSDKKey("Your SDK")  //change sdk
                .build(getApplicationContext());
        WorkerScheduler.requestOnlyWhenConnected = false;
        EyeofcloudClient eyeofcloudClient = eyeofcloudManager.initialize(getApplicationContext(), R.raw.datafile);
        if(eyeofcloudClient.isValid()) {
            Random rnd = new Random();
            boolean hasOnFlags = false;
            for (int i = 0; i < 10; i++) {
                String userId = (rnd.nextInt(9999 - 1000) + 1000) + "";
            /* --------------------------------
                Create hardcoded user & bucket user into a flag variation
                --------------------------------
            */
                EyeofcloudUserContext user = eyeofcloudClient.createUserContext(userId);
                // "product_sort" corresponds to a flag key in your Eyeofcloud project
                EyeofcloudDecision decision = user.decide("product_sort");
                // did decision fail with a critical error?
                if (decision.getVariationKey() == null) {
                    System.out.println("\n\ndecision error: " + decision.getReasons());
                }
                // get a dynamic configuration variable
                // "sort_method" corresponds to a variable key in your Eyeofcloud project
                String sortMethod = null;
                try {
                    sortMethod = decision.getVariables().getValue("sort_method", String.class);
                } catch (Exception e) {
                    e.printStackTrace();
                }

                if (decision.getEnabled()) {
                    // Keep count how many visitors had the flag enabled
                    hasOnFlags = true;
                }
                /* --------------------------------
                    Mock what the users sees with print statements (in production, use flag variables to implement feature configuration)
                    --------------------------------
                */
                // always returns false until you enable a flag rule in your Eyeofcloud project
                String enabled = decision.getEnabled() ? "on" : "off";

                System.out.println("\n\nFlag " + enabled + ". User number " + user.getUserId() + " saw flag variation: " + decision.getVariationKey() + " and got products sorted by: " + sortMethod + " config variable as part of flag rule: " + decision.getRuleKey());
            }
            if (!hasOnFlags) {
                System.out.println("\n\nFlag was off for everyone. Some reasons could include:" +
                        "\n1. Your sample size of visitors was too small. Rerun, or increase the iterations in the FOR loop" +
                        "\n2. By default you have 2 keys for 2 project environments (dev/prod). Verify in Settings>Environments that you used the right key for the environment where your flag is toggled to ON." +
                        "\n\nCheck your key at  https://app.eyeofcloud.com/v2/projects/" + eyeofcloudClient.getProjectConfig().getProjectId() + "settings/implementation");
            }
        }
        else {
            System.out.println("Eyeofcloud client invalid. Verify in Settings>Environments that you used the primary environment's SDK key");
        }
        // close before exit to flush out queued events
        eyeofcloudClient.close();
    }
}

在AndroidManifest.xml文件中添加发送请求权限

<uses-permission android:name="android.permission.INTERNET"/>

📘 注意
暂时不要运行应用程序，因为仍然需要在云眼应用程序中设置标帜。

第二部分：运行应用

完成第一部分后，应用将不执行任何操作。需要在云眼应用程序中创建标帜和标帜规则才能启用该应用程序。

1. 创建灰度标帜(Feature Flag)

通过灰度标帜(Feature Flag)，可以控制在应用中看到新功能代码的用户。对于本快速入门，假设你正在推出一个重新设计的排序功能来显示产品。

在云眼中创建一个名为 product_sort 的标帜，并为其提供一个名为 sort_method 的变量：

转到标帜>创建标帜。
将标帜键命名为_product_sort_，然后单击**“创建标帜**”，该标帜对应于示例应用中的标帜键。
转到默认变量，然后单击新建 （+）。
将变量类型设置为字符串。
将变量命名_为 sort_method_，该名称对应于示例应用中的变量键。
将变量默认值设置为_字母顺序_，表示旧的排序方法。

单击右下角的保存以保存变量。
转到变体**，**然后点击默认的“开启”变体。变体是变量值集合的包装器。
将sort_method变量值设置为 popular_first，表示新的排序方法。

单击保存。

2. 创建标帜传递规则

示例应用仍不执行任何操作，因为需要在应用中创建并启用标帜规则。

为_product_sort_标帜的“开启”变体制定有针对性的投放规则。有针对性的交付允许逐步向用户发布灰度标帜(Feature Flag)，但可以灵活地在遇到错误时将其回滚。

验证您是否在主环境中（因为您使用的是主环境 SDK 密钥）：

点击添加规则，然后选择_定向投放_。
将流量滑块设置为 50%。这会将标帜传递给在此环境中触发标帜的每个人的 50%。可以随时将product_sort标帜推出或回滚到流量的百分比。
从“传递”下拉列表中，选择“打开”。
单击保存。

为标帜规则启用标帜：

3. 运行示例应用

在 Android Studio 中，针对之前创建的示例控制台应用单击“运行”。输出类似于以下内容：

文本

Flag on. User number 9591 saw flag variation: off and got products sorted by: 购买 config variable as part of flag rule: default-rollout-182-270
Flag on. User number 5488 saw flag variation: off and got products sorted by: 购买 config variable as part of flag rule: default-rollout-182-270
Flag on. User number 2660 saw flag variation: new_variation1 and got products sorted by: 立即购买 config variable as part of flag rule: buy_experiment
Flag on. User number 9952 saw flag variation: off and got products sorted by: 购买 config variable as part of flag rule: default-rollout-182-270
Flag on. User number 5152 saw flag variation: new_variation1 and got products sorted by: 立即购买 config variable as part of flag rule: buy_experiment
Flag on. User number 5074 saw flag variation: off and got products sorted by: 购买 config variable as part of flag rule: default-rollout-182-270
Flag on. User number 4898 saw flag variation: new_variation1 and got products sorted by: 立即购买 config variable as part of flag rule: buy_experiment
Flag on. User number 2396 saw flag variation: new_variation1 and got products sorted by: 立即购买 config variable as part of flag rule: buy_experiment
Flag on. User number 8713 saw flag variation: off and got products sorted by: 购买 config variable as part of flag rule: default-rollout-182-270
Flag on. User number 9365 saw flag variation: new_variation1 and got products sorted by: 立即购买 config variable as

📘 注意：
在“开启”变体中，您不会获得恰好 50% 的用户流量，因为您正在与如此少量的访问者合作。此外，获得“关闭”标帜的用户没有进入您设置的 50% 流量，因此他们跌落到默认的“关闭”规则（前面的打印语句中的_默认推出_）：

4. 工作原理

到目前为止，您有：

在云眼应用程序中创建了标帜、标帜变量和标帜变体（变量的包装器）
使用 Decide 方法在应用中实现了标帜

工作原理：决定向用户显示标帜

SDK 的 Decision（决定）方法确定是显示还是隐藏特定用户的灰度标帜(Feature Flag)。

📘 注意
可以将此方法重用于不同的标帜规则，无论是向更多流量投放，还是运行实验以仅向部分用户展示不同的排序方法。

了解哪种排序方法最能提高销售额后，请将产品排序标帜推广到所有流量，并将该方法设置为最佳值。

在示例应用中：

Java

EyeofcloudUserContext user = eyeofcloudClient.createUserContext(userId);
// "product_sort" corresponds to the flag key you create in the Eyeofcloud app
EyeofcloudDecision decision = user.decide("product_sort");

📘 注意
（可选）在创建用户时包括属性（未显示在示例应用中），以便可以定位特定受众。例如：

Java

Map attributes = new HashMap<String, Object>();
attributes.put("logged_in", true);
EyeofcloudUserContext user = eyeofcloudClient.createUserContext("user123", attributes);

工作原理：配置标帜变体

可以使用标帜变量动态配置标帜变体。在示例应用中：

Java

// always returns false until you enable a flag rule in the Eyeofcloud app
if (decision.getEnabled()) {
    // "sort_method" corresponds to variable key you define in Eyeofcloud app
    Object sortMethod = decision.getVariables().toMap().get("sort_method");
    System.out.println("sort_method: "+ sortMethod.toString());
}

对于product_sort标帜，可以配置具有不同sort_method值的变体，按热门产品、相关产品、推广产品等进行排序。可以随时在云眼应用程序中为排序方法设置不同的值。

第三部分：运行 A/B 测试

本教程只是指导您完成有针对性的交付，因为它是最简单的标帜规则。但是，在推出灰度标帜(Feature Flag)传递之前，你通常需要对用户_对_灰度标帜(Feature Flag)变体的反应进行 A/B 测试。

下表显示了标帜传递和 A/B 测试之间的差异：

目标投放规则

A/B 测试规则

可以将标帜推广到一定比例的一般用户群（或特定受众），或者在遇到错误时回滚。

在投资交付之前，通过 A/B 测试标帜进行实验，这样您就知道要构建什么。跟踪用户在标帜变体中的行为，然后使用云眼统计引擎解释实验结果。

现在，A / B测试product_sort标帜的“on”变体。

1. 添加事件跟踪

需要将跟踪事件方法添加到示例应用，以便可以模拟用户事件，然后查看指标。

删除旧的示例代码，并粘贴以下代码。
请记得再次更换开发工具包密钥。
不要运行应用程序，因为仍然需要在云眼应用程序中设置 A/B 测试。

Java

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;

import com.eyeofcloud.ab.EyeofcloudUserContext;
import com.eyeofcloud.ab.android.sdk.EyeofcloudClient;
import com.eyeofcloud.ab.android.sdk.EyeofcloudManager;
import com.eyeofcloud.ab.android.shared.DatafileConfig;
import com.eyeofcloud.ab.android.shared.WorkerScheduler;
import com.eyeofcloud.ab.event.internal.EventFactory;
import com.eyeofcloud.ab.eyeofclouddecision.EyeofcloudDecision;

import java.util.Random;
import java.util.concurrent.TimeUnit;

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

//        initEyeofcloud();
        // change datafileHost
        DatafileConfig.defaultHost = "https://cdn.eyeofcloud.com";
        // change eventHost
        EventFactory.EVENT_ENDPOINT = "https://event.eyeofcloud.com/v1/events";

        EyeofcloudManager eyeofcloudManager = EyeofcloudManager.builder()
                .withEventDispatchInterval(1L, TimeUnit.SECONDS)
                .withDatafileDownloadInterval(15, TimeUnit.MINUTES)
                .withSDKKey("1000563_ebf080bb426e7555")  //change sdk
                .build(getApplicationContext());
        WorkerScheduler.requestOnlyWhenConnected = false;
        EyeofcloudClient eyeofcloudClient = eyeofcloudManager.initialize(getApplicationContext(), R.raw.datafile);
        if(eyeofcloudClient.isValid()) {
            Random rnd = new Random();
            boolean hasOnFlags = false;
            for (int i = 0; i < 10; i++) {
                String userId = (rnd.nextInt(9999 - 1000) + 1000) + "";
            /* --------------------------------
                Create hardcoded user & bucket user into a flag variation
                --------------------------------
            */
                EyeofcloudUserContext user = eyeofcloudClient.createUserContext(userId);
                // "product_sort" corresponds to a flag key in your Eyeofcloud project
                EyeofcloudDecision decision = user.decide("product_sort");
                // did decision fail with a critical error?
                if (decision.getVariationKey() == null) {
                    System.out.println("\n\ndecision error: " + decision.getReasons());
                }
                // get a dynamic configuration variable
                // "sort_method" corresponds to a variable key in your Eyeofcloud project
                String sortMethod = null;
                try {
                    sortMethod = decision.getVariables().getValue("sort_method", String.class);
                } catch (Exception e) {
                    e.printStackTrace();
                }

                if (decision.getEnabled()) {
                    // Keep count how many visitors had the flag enabled
                    hasOnFlags = true;
                }
                /* --------------------------------
                    Mock what the users sees with print statements (in production, use flag variables to implement feature configuration)
                    --------------------------------
                */
                // always returns false until you enable a flag rule in your Eyeofcloud project
                String enabled = decision.getEnabled() ? "on" : "off";

                System.out.println("\n\nFlag " + enabled + ". User number " + user.getUserId() + " saw flag variation: " + decision.getVariationKey() + " and got products sorted by: " + sortMethod + " config variable as part of flag rule: " + decision.getRuleKey());

                MockPurchase(user);
            }
            if (!hasOnFlags) {
                System.out.println("\n\nFlag was off for everyone. Some reasons could include:" +
                        "\n1. Your sample size of visitors was too small. Rerun, or increase the iterations in the FOR loop" +
                        "\n2. By default you have 2 keys for 2 project environments (dev/prod). Verify in Settings>Environments that you used the right key for the environment where your flag is toggled to ON." +
                        "\n\nCheck your key at  https://app.eyeofcloud.com/v2/projects/" + eyeofcloudClient.getProjectConfig().getProjectId() + "settings/implementation");
            }
        }
        else {
            System.out.println("Eyeofcloud client invalid. Verify in Settings>Environments that you used the primary environment's SDK key");
        }
        // close before exit to flush out queued events
        eyeofcloudClient.close();
    }
    
    // mock tracking a user event so you can see some experiment reports
    static void MockPurchase(EyeofcloudUserContext user) {
        System.out.println("Pretend that user made a purchase? y/n ");
        Random random = new Random();
        String selected = random.nextBoolean() ? "y": "n";
        System.out.println(selected);
        if (selected.equals("y")) {
            // track a user event you defined in the Eyeofcloud app
            user.trackEvent("buy");
            System.out.println("Eyeofcloud recorded a purchase in experiment results for user " + user.getUserId());
        } else {
            System.out.println("Eyeofcloud didn't record a purchase in experiment results for user " + user.getUserId());
        }
    }
}

2. 暂停免费帐户中的其他规则

如果你有免费帐户，则需要在保存 A/B 测试之前暂停之前在本快速入门中创建的目标交付：

选择包含您计划暂停的目标投放的特定标帜。

选择要暂停的环境和目标投放。
单击右上角的禁用规则按钮。

3. 创建 A/B 测试

要在云眼项目中创建和启动实验，请执行以下操作：

转到旗帜的规则。
单击“> A/B 测试添加规则”。

4. 添加事件

在实验中，将跟踪用户的相关操作，以衡量用户对灰度标帜(Feature Flag)变体的反应。需要定义要跟踪的操作：

单击**“指标**”字段。
点击创建新活动。

对于事件密钥，输入_购买_并单击创建事件。（您想知道新的排序标帜是否帮助客户确定要购买什么，因此请跟踪用户在新订单中显示产品后是否进行了购买。

2021-03-24 12_27_01-product_sort_ Flags_ Rules_ Development_ Experiment - 云眼.png

保留默认值（衡量_唯一身份转化_次数_的增加_）。

点击添加指标。
将默认的“关闭”变体保留为控件。选择您在上一步中配置的“开”变体：

单击保存。

📘 注意
您不限于两种变体;还可以创建具有多个变体的 A/B 测试。例如：

仔细检查标帜以确保它处于开启状态，以便实验可以运行：

5. 运行 A/B 测试

单击“在 Android Studio 中运行”并回答命令行提示。输出类似于以下内容：

文本

Flag on. User number 2613 saw flag variation: new_variation1 and got products sorted by: 立即购买 config variable as part of flag rule: buy_experiment
Pretend that user made a purchase? y/n 
n
Eyeofcloud didn't record a purchase in experiment results for user 2613


Flag on. User number 9770 saw flag variation: off and got products sorted by: 购买 config variable as part of flag rule: default-rollout-182-270
Pretend that user made a purchase? y/n 
y
Eyeofcloud recorded a purchase in experiment results for user 9770


Flag on. User number 5198 saw flag variation: off and got products sorted by: 购买 config variable as part of flag rule: default-rollout-182-270
Pretend that user made a purchase? y/n 
y
Eyeofcloud recorded a purchase in experiment results for user 5198


Flag on. User number 8080 saw flag variation: off and got products sorted by: 购买 config variable as part of flag rule: default-rollout-182-270
Pretend that user made a purchase? y/n 
n
Eyeofcloud didn't record a purchase in experiment results for user 8080


Flag on. User number 8956 saw flag variation: new_variation1 and got products sorted by: 立即购买 config variable as part of flag rule: buy_experiment
Pretend that user made a purchase? y/n 
y
Eyeofcloud recorded a purchase in experiment results for user 8956

6. 查看 A/B 测试结果

转到“报告”标签以查看实验结果。

结果如下所示：

📘 注意
在拥有更多用户之前，开发者可能不会看到为标帜变体配置的确切用户流量百分比。
开发者可能不会立即看到用户流量。刷新浏览器以刷新流量，
在有大量访问者（大约 100，000 人）之前，实验结果不会告诉您获胜变体。

7. 工作原理

对于 A/B 测试，需要一种方法来告知云眼用户何时在应用中进行了购买，并将应用代码中的此事件映射到您在云眼中创建的特定事件。幸运的是，SDK有一种方法。使用 Track Event 方法并传入所创建事件的密钥（）。在示例应用中：purchase

Java

// Track how users behave when they see a flag variation
// e.g., after your app processed a purchase, let Eyeofcloud know what happened:
user.trackEvent("purchased");

📘 注意
（可选）向事件添加标签以丰富事件（未显示在示例应用中）。还可以使用收入等备用标签键来跟踪定量结果。例如：

Java

Map tags = new HashMap<String, Object>();
tags.put("category", "shoes");
tags.put("revenue", 6432);

 user.trackEvent("purchase", tags);

目前仅实验规则支持事件跟踪，不支持投放规则。未来变体将支持跟踪交货。

无论哪种方式，在实现标帜时都应包括事件跟踪，因为它可以帮助与第三方分析平台集成，并且在创建 A/B 测试时提供灵活性。

结论

祝贺！您已成功设置并启动了第一个云眼灰度标帜(Feature Flag)AB实验。虽然此示例侧重于优化销售，但云眼的实验平台可以支持一组开放式的实验用例。

请参阅我们完整的 Android SDK 文档，了解使用实验优化软件的更多方法。