敏捷开关 微信小程序 SDK

Check English version

查看 demo

发布小程序前请确保已将 https://api.featureflag.co 添加到小程序合法域名中

概述

SDK 主要完成以下工作:

• 从服务端获取 feature flags 并保持和服务端数据的同步。

数据同步

SDK 使用 WebSocket 来保持与服务端的数据同步，从服务端获取的数据均会存入 localStorage。无论何时当任意 feature flag 发生变化时，变更会被接近实时地推送到 SDK，经过测试，同步过程平均耗时少于 100 ms。当网络发生中断时 SDK 会尝试以渐增的时间间隔与服务器重新建立连接，及时恢复数据同步。

离线模式

SDK 所需的所有数据都存储于本地 localStorage, 因此在没有网络的环境中，满足下述条件之一的情况下，SDK 仍能正常工作：

• SDK 已经从之前的 WebSocket 连接中取得过数据
• ffcClient.bootstrap(featureFlags) 方法被手动调用， 并且 featureFlags 参数包含所有当前使用中的 feature flags

feature flag 的计算

所有数据都在本地，所有计算过程也都在本地，并且是实时同步计算的。计算过程时间复杂度 O(1), 小于 1 ms。

集成 SDK

使用 npm

前往 project.config.json 文件中 miniprogramRoot 参数指定的文件夹并运行如下命令:

npm install ffc-wechat-miniprogram-sdk --save

引入 SDK:

import ffcClient from 'ffc-wechat-miniprogram-sdk';

不使用 npm

1. 从 github 克隆项目到本地

git clone https://github.com/feature-flags-co/ffc-wechat-miniprogram-sdk.git

2. 运行如下命令编译代码

cd ffc-wechat-miniprogram-sdk
npm i
npm run build

3. 将 dist 文件夹复制到小程序项目根目录并且重新命名为 ffc-wechat-miniprogram-sdk

4. 引入 SDK:

import ffcClient from 'path to ffc-wechat-miniprogram-sdk/index';

初始化 SDK

初始化之前请确保从敏捷开关后台获取对应项目环境的 secret。

import ffcClient from 'ffc-wechat-miniprogram-sdk'; // use path to your sdk if you are not using npm

App({
  globalData: {
  },
  onLaunch() {
    const option = { // you can specify the type with IOption if using Typescript
      secret: "your env secret",
      user: {
        userName: "the user's user name",
        id: "the user's unique identifier"
      }
    };

    // initialize client
    ffcClient.init(option);

    // set user，this usually happens after login
    const user = { // you can specify the type with IUser if using Typescript
      "userName": "the user's user name",
      "id": "the user's unique identifier" // the unique user Id, can be wechat id
      ]
    };

    ffcClient.identify(user);
  },
  ...
})

以下为完整的参数列表：

• secret: 项目环境的 secret. 必填项 (注意: 如果 enableDataSync 设置为false， 则 secret 可以为空)
• anonymous: 如果值为 true 则使用匿名用户， 登录之后可以调用 identify() 方法来切换用户。默认值为 false. 必填项
• bootstrap: 使用本地 feature flags 初始化 SDK。当提供此参数时将会立即触发 ready event。 非必填项
• enableDataSync: 如果值为 false 则不会与服务器进行数据同步，这时请确保通过 bootstrap 参数提供了所有的 feature flags 或者通过 bootstrap() 方法传入所有 feature flags。 默认值为 true。 非必填项
• api: 服务端地址，默认值为敏捷开关服务器地址。只有在使用 self-host 服务端时才需要提供此参数。 非必填项
• user: 当前用户，如果 anonymous 参数设置为 true 则 无需提供 user。
  • userName: 用户名. 必填项
  • id: 用户唯一 id. 必填项
  • email: 可以在设置 feature flag 规则时使用，也可以在用户列表中查看。 非必填项
  • country: 可以在设置 feature flag 规则时使用 非必填项
  • customizedProperties: 可以是任何希望发送给服务器的用户自定义属性。在定义 feature flag 规则或用户组时将会非常有用。 非必填项
    • 必须符合如下数据格式:

     [{
       "name": "the name of the property",
       "value": "the value of the property"
     }]

初始化过程延迟时间

SDK 初始化时会向服务器发送请求并建立 WebSocket 连接， 这个过程耗时 100 毫秒左右。如果希望 feature flags 立即可用，可以在初始化时通过 bootstrap 提供本地 feature flags, 这时会立即触发 ready event。初始化完成后 SDK 会用服务端数据替换本地数据。

获取 feature flag 的值

SDK 会将 flagConfigs 中配置的 feature flags 自动生成一个 flags 对象并填充到 Page 或者 Component 的 data 中，JavaScript 代码中引用方式为 this.data.flags['flagkey'], wxml 中则可以通过 flags['flagkey'] 方式引用。

import ffcClient from "ffc-wechat-miniprogram-sdk";

// Typescript 类型为 IFlagConfig[]
// 服务端支持直接定义开关返回值类型，defaultValue 应该使用和服务端定义的相同的类型
// 目前支持四种数据类型：string, boolean, number 和 json
const flagConfigs = [
  { key: 'flagkey', defaultValue: defaultValue }
];

// 使用 Page
Page({
  data: {
    flagConfigs,
  },
  onLoad() {
    // 从 data 中获取开关值
    console.log(this.data.flags['flagkey']);

    // 从 SDK 直接获取开关值
    // ffcClient.variation() 和 this.data.flags['flagkey'] 实现相同的效果
    // 服务端支持直接定义开关返回值类型，defaultValue 应该使用和服务端定义的相同的类型
    // 目前支持四种数据类型：string, boolean, number 和 json
    const variation = ffcClient.variation('flagkey', defaultValue);
    console.log(variation);

    // 监听具体某个开关返回值的变化
    ffcClient.on(`ff_update:flagkey`, (change) => {
      // change 的结构为 {id: 'the feature_flag_key', oldValue: old_value, newValue: new_value}
      // 其中 old_value 和 new_value 具有和服务端定义的相同的数据类型
      console.log(change.newValue);
    });
  },
  ...
})

// 使用 Component
Component({
  data: {
    flagConfigs,
  },
  attached() {
    // 从 data 中获取开关值
    console.log(this.data.flags['flagkey']);

    // 从 SDK 直接获取开关值
    // ffcClient.variation() 和 this.data.flags['flagkey'] 实现相同的效果
    // 服务端支持直接定义开关返回值类型，defaultValue 应该使用和服务端定义的相同的类型
    // 目前支持四种数据类型：string, boolean, number 和 json
    const variation = ffcClient.variation('flagkey', defaultValue);
    console.log(variation);

    // 监听具体某个开关返回值的变化
    ffcClient.on(`ff_update:flagkey`, (change) => {
      // change 的结构为 {id: 'the feature_flag_key', oldValue: old_value, newValue: new_value}
      // 其中 old_value 和 new_value 具有和服务端定义的相同的数据类型
      console.log(change.newValue);
    });
  },
  ...
})


// 在 wxml 文件中使用开关，当开关返回值发生变化时，页面内容会自动刷新
<view class="container">
  <view>
    <text>{{flags['flagkey']}}</text>
  </view>
</view>

bootstrap

如果初始化 SDK 之前已经有所有 feature flags，则可以使用以下任意一种方法将其传给 SDK：

• 通过 init 方法

  // 在 option 中定义初始化开关
  const option = {
    ...
    bootstrap = [{ // the array should contain all your feature flags
      id: string, // the feature flag key
      variation: string,
      sendToExperiment: boolean, // ignore this for now
      timestamp: number,
      variationOptions: [{ // all possible variation of the feature flag
        id: number,
        value: string
      }]
    }]
    ...
  }

  ffcClient.init(option);

• 通过 bootstrap 方法

const featureflags = [{ // the array should contain all your feature flags
  id: string, // the feature flag key
  variation: string,
  sendToExperiment: boolean,
  timestamp: number,
  variationOptions: [{ // all possible variation of the feature flag
    id: number,
    value: string
  }]
}]

ffcClient.bootstrap(featureflags);

可以将参数 enableDataSync 设置为 false 以停止和服务器间的数据同步。这时必须提供 bootstrap 参数或者调用 bootstrap() 方法以提供本地版的 feature flags 数据。

可以使用 event 或者 promise 等待 SDK 初始化结束。

SDK 在初始化完成后会自动触发 ready event。可以在代码中监听 ready 事件来确保获取开关值之前本地已经取得数据。

ffcClient.on('ready', (data) => {
  // data 的结构为 [ {id: 'featureFlagKey', variation: variation_value} ]
  // variation_value 具有和服务端定义的相同的数据类型
  var flagValue = Ffc.variation("YOUR_FEATURE_KEY", 'the default value');
});

或者也可以使用 promise。SDK 提供了 waitUntilReady() 方法，和 ready 事件实现相同的效果，但是提供了 promise API, 同时支持使用 await。

ffcClient.waitUntilReady().then((data) => {
  // data 的结构为 [ {id: 'featureFlagKey', variation: variation_value} ]
  // variation_value 具有和服务端定义的相同的数据类型
  // 初始化完成，可以正常使用开关
});
// 或者，使用 await:
const featureFlags = await ffcClient.waitUntilReady();
// 初始化完成，可以正常使用开关

初始化结束之后切换用户

如果初始化时使用了匿名用户，登录后我们往往需要切换到登录后的用户，这时可以使用 identity() 方法来切换用户。

  ffcClient.identify(user);

重新切换为匿名用户

当用户退出账户时可以调用 logout() 方法重新切换为匿名用户。

  ffcClient.logout(user);

监听 feature flag 变更事件

SDK 提供了两种方法来监听 feature flag 变更事件：

• 监听所有 feature flags 的变动

ffcClient.on('ff_update', (changes) => {
  // change 的结构为 [{id: 'the feature_flag_key', oldValue: old_value, newValue: new_value}]
  // 其中 old_value 和 new_value 具有和服务端定义的相同的数据类型
  ...
});

• 监听某个具体 feature flag 的变动

// 将 feature_flag_key 替换为自己开关的 key
ffcClient.on('ff_update:feature_flag_key', (change) => {
  /// change 的结构为 {id: 'the feature_flag_key', oldValue: old_value, newValue: new_value}
  // 其中 old_value 和 new_value 具有和服务端定义的相同的数据类型
  ...
});