文档

初始化

更新时间:

本文介绍客户端SDK建立长连接前的初始化步骤。

说明

  • 初始化接口,是客户端SDK准备资源,与服务端建立连接的步骤。

  • 本接口参数主要包含appId、appKey、deviceId和token回调函数,以下各参数的详细说明:

    • appId,应用Id,用作标识应用,可以在应用管理页 应用列表中获得。

    • appKey,用作标识客户端类型的字符串,可以在应用管理页的应用列表中获得Android、iOS、PC、Web的对应值。

    • deviceId,用作标识当前设备的唯一Id,如何获取deviceId,请参考下方各端的API使用示例。

    • token回调函数,token回调函数是提供给SDK内部调用,用来获取建连所需要的token令牌。在回调函数的实现里,需要开发者调用自己的应用服务提供的接口来获取到token信息,并将token返回给SDK,SDK通过token与服务端建立连接。

说明

应用服务端如何获取token请参考接口说明GetAuthToken - 获取长链接建连Token。注意,SDK内部包含登录态的缓存信息,因此并不是每次建连SDK都会通过该回调函数来取token信息。

API使用示例

iOS端接口使用示例

//先构造和配置初始化用的配置对象AIRBRoomEngineConfig
// appID和appKey都是在控制台创建好应用后获得;
// deviceID在iOS端可以默认使用设备的UUID
AIRBRoomEngineConfig* roomEngineConfig = [[AIRBRoomEngineConfig alloc] init];
roomEngineConfig.appID = @"xxxxx";
roomEngineConfig.appKey = @"xxxxx";
roomEngineConfig.deviceID = [[UIDevice currentDevice] identifierForVendor].UUIDString;

//为了更好的监听AIRBRoomEngine初始化返回的结果,需要设置AIRBRoomEngineDelegate并实现对应方法
[AIRBRoomEngine sharedInstance].delegate = self;

//进行初始化
[[AIRBRoomEngine sharedInstance] globalInitOnceWithConfig:self.roomEngineConfig];

//初始化成功,需要通过监听AIRBRoomEngine的AIRBRoomEngineEventEngineStarted事件来获取,如下
- (void) onAIRBRoomEngineEvent:(AIRBRoomEngineEvent)event info:(NSDictionary *)info {
    LOG("ASLRBLoginManager::onAIRBRoomEngineEvent(%ld, %@)", (long)event, info);
    switch (event) {
        case AIRBRoomEngineEventEngineStarted:
            //初始化成功
            break;
        default:
            break;
    }
}

//初始化失败,需要通过监听AIRBRoomEngine返回的错误事件AIRBEngineFailedToStart和AIRBEngineFailedToCreateDPSManager
- (void) onAIRBRoomEngineErrorWithCode:(AIRBErrorCode)code errorMessage:(NSString *)msg {
    switch (code) {
        case AIRBEngineFailedToStart:
            NSLog(@"初始化失败,%@", msg);
            break;
        case AIRBEngineFailedToCreateDPSManager:
            NSLog(@"初始化失败,%@", msg);
            break;
        default:
            break;
    }
}

Android端接口使用示例

// 构建应用初始化时的必要信息,请使用你的应用的appId和appKey,替换示例中的<appId>、<appKey>占位符。
EngineConfig config = new EngineConfig.Builder()
        .appId("<appId>")
        .appKey("<appKey>")
        .deviceId("<deviceId>")
        .tokenInfoGetter(new TokenInfoGetter() {
            @Override
            public void getTokenInfo(String userId, Callback<TokenInfo> callback) {
                // GetTokenApi中调用业务服务端接口获取token信息,然后通过callback回传给SDK内部
                GetTokenApi.getToken(userId, callback);
            }
        })
        .build();

// SDK初始化
RoomEngine.getInstance().init(context, config, new Callback<Void>() {
    @Override
    public void onSuccess(Void data) {
        // 初始化成功之后, 执行后续的建连操作
        doLogin(callback);
    }
    @Override
    public void onError(String errorMsg) {
        Logger.e(TAG, "dps engine init fail: " + errorMsg);
    }
});

Web端接口使用示例

// 获取设备号deviceId,唯一标识当前设备
// 在web端,不同的tab页代表不同设备
const deviceId = RoomEngine.getInstance().getDeviceId();

// 配置参数
const config = {
  appKey, // 创建应用时分配的appKey
  appID, // 创建应用时分配的appId
  deviceId, // 设备号
  authTokenCallback, // 获取登录token的回调函数,需要返回Promise
}
// 传入配置
 
RoomEngine.getInstance().init(config);

Windows端接口使用示例

class Const {
public:
  /**
   * kAppId (来自于阿里云控制台),考虑到安全问题,不建议写死在客户端,应通过业务服务器获取
   */
  const static std::string kAppId;
  /**
   * APP_KEY (来自于阿里云控制台),考虑到安全问题,不建议写死在客户端,应通过业务服务器获取
   */
  const static std::string kAppKey;
  /**
   * 验签公钥 (用户服务端按需选择),考虑到安全问题,不建议写死在客户端,应通过业务服务器获取
   */
  const static std::string kSignSecret;
  /**
   * 用户服务端链接地址 (接入时替换为自己的服务地址)
   */
  const static std::string kAppServerUrl;
};
auto meta_space = MetaSpace::GetInstance();
if (meta_space) {
  MetaSpaceContext ctx;
  ctx.app_id = Const::kAppId;
  ctx.app_key = Const::kAppKey;
  //获取设备信息,建议使用硬盘编号,然后md5
  ctx.device_id = GetDeviceId();
  std::string path_str;
  ctx.data_path = path_str;
  ctx.env = (int32_t)alibaba::meta::EnvType::ENV_ONLINE;
  meta_space->Init(ctx, [&]() { }, [&](const alibaba::dps::DPSError& err) {
     // 初始化失败,打日志
  });
  meta_space->SetLogHandler(alibaba::meta::LogLevel::LOG_LEVEL_DEBUG,
    [](alibaba::meta::LogLevel log_level,const std::string& log_content) {});
}

authTokenCallback说明

authTokenCallback是一个返回Promise的函数,可以用以下的方式编写:

  • 可以使用任何能返回Promise的请求库或API(如axios或fetch等)。

  • 可以自己构造Promise,在resolve里返回结果。

  • 可以使用async函数,直接return结果。

下面用fetch API举例:

const authTokenCallback: Promise<AuthToken> = () => {
  const origin = 'xxx.xxx.com'; // 客户的域名
  const path = 'api/getToken'; // 客户服务端接口
  // fetch API返回一个Promise
  return fetch(`${origin}/${path}?userId=123&foo=bar`) // 这里由客户自己定义接口需要的数据
    .then((res) => res.json())
    .then((res) => {
      if (res) {
        // 需要保证数据结构符合AuthToken,其定义在下面
        const authToken: AuthToken = res.result; // 这里需要根据客户服务端返回的数据结构来决定返回什么属性
        return authToken;
      }
      throw new Error('没有获取到Token');
    })
    .catch((err) => {
      console.error(err);
    });
}

resolve的值来源于客户服务端SDK的接入回调,数据结构为:

interface AuthToken {
  accessToken: string;
  refreshToken: string;
  accessTokenExpiredTime: number;
}