SDK初始化

更新时间：2026-10-30 11:38:30

SDK初始化

建议在 EntryAbility.ets 中对 SDK 进行初始化操作，只有SDK初始化完成以后才可以调用SDK相关接口，否则会出现接口调用异常。

// 导入初始化SDK
import { RTCXSDKInit, RTCXSDKInitTypes, RTCXCommonTypes, RTCXLogger } from 'rtcxsdk'

接口说明

初始化SDK

/**
 * 初始化SDK
 * @param context - 应用上下文
 * @param config - 初始配置项
 * @returns
 * @public
 */
export declare function init(context: Context, config: InitConfig): Promise<void>;

反初始化SDK

/**
 * 反初始化SDK
 * @public
 */
export declare function uninit(): Promise<void>;

获取当前数据中心ID

/**
 * 获取当前数据中心ID，未解析到时返回 -1
 * @public
 */
export declare function getRegionId(): number;

获取接入区域

/**
 * 获取接入区域（国内或海外）
 * @public
 */
export declare function getRegionType(): RegionTypeEnum;

配置项

SDK 初始化配置项如下：

/**
 * SDK初始化配置
 * @public
 */
export declare class InitConfig {
  /**
   * 接入区域（国内或海外），默认 REGION_CHINA_ONLY
   */
  regionType: RegionTypeEnum;

  /**
   * 环境，默认 PROD
   */
  productEnv: PlatformEnvEnum;

  /**
   * 是否开启日志调试，默认 false
   */
  debug: boolean;

  /**
   * 通用版App配置项
   */
  appKeyConfig?: AppKeyConfig;

  /**
   * 专属版App配置项，接入方式见“专属版SDK”
   */
  specialAppKeyConfig?: AppKeyConfig;

  /**
   * 专属版数据中心 regionId（对应 iOS privRegionId），不设置时默认 0
   */
  specialRegionId?: number;

  /**
   * 专属版初始化结果回调，与通用版初始化互不阻塞
   */
  specialSdkInitFinishedCallback?: SpecialSdkInitCallback;
}

/**
 * App配置项
 * @public
 */
export declare class AppKeyConfig {
  /**
   * 数据中心服务协议，默认 HTTPS
   */
  dataCenterScheme: ServerSchemeEnum;

  /**
   * 数据中心服务域名，如：datacenter.example.com
   * 也支持携带协议前缀，如：https://datacenter.example.com
   */
  dataCenterDomain?: string;

  /**
   * 信令协议，默认 WSS
   */
  signalingScheme: ServerSchemeEnum;

  /**
   * 信令域名
   */
  signalingDomain?: string;

  /**
   * 控制台创建的应用 appKey
   */
  appKey: string;

  /**
   * 控制台创建的应用 appSecret
   */
  appSecret: string;
}

/**
 * 专属版初始化结果回调
 * @public
 */
export type SpecialSdkInitCallback = (success: boolean, error?: Error) => void;

字段	必填	说明
`appKeyConfig.appKey`	接入通用版时必填	平台分配的 appKey
`appKeyConfig.appSecret`	接入通用版时必填	平台分配的 appSecret
`appKeyConfig.dataCenterScheme`	否	数据中心服务协议，默认 `HTTPS`，全量私有化时使用
`appKeyConfig.dataCenterDomain`	否	数据中心服务域名，全量私有化时使用
`appKeyConfig.signalingScheme`	否	信令协议，默认 `WSS`
`appKeyConfig.signalingDomain`	否	信令域名，不设置时使用平台默认信令域名
`regionType`	否	接入区域，默认 `REGION_CHINA_ONLY`，海外接入需设置为 `REGION_ALL`
`productEnv`	否	环境，可选 `LOCAL`、`TEST`、`PROD`，默认 `PROD`
`debug`	否	是否开启日志调试，默认 `false`
`specialAppKeyConfig` 等专属版字段	否	见专属版SDK

初始化示例

import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
import { RTCXSDKInit, RTCXSDKInitTypes, RTCXCommonTypes, RTCXLogger } from 'rtcxsdk'

const DOMAIN = 0x0000;

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    try {
      this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET);
    } catch (err) {
      hilog.error(DOMAIN, 'testTag', 'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
    }
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Splash', (err) => {
      if (err.code) {
        hilog.error(DOMAIN, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
        return;
      }
      this.initSDK()
    });
  }

  initSDK() {
    const appKeyConfig = new RTCXSDKInitTypes.AppKeyConfig()
    appKeyConfig.appKey = 'your_app_key'
    appKeyConfig.appSecret = 'your_app_secret'

    const initConfig = new RTCXSDKInitTypes.InitConfig()
    initConfig.appKeyConfig = appKeyConfig
    // 接入海外时设置为 REGION_ALL，并在初始化完成后设置国家
    initConfig.regionType = RTCXCommonTypes.RegionTypeEnum.REGION_CHINA_ONLY
    initConfig.productEnv = RTCXCommonTypes.PlatformEnvEnum.PROD
    initConfig.debug = true

    RTCXSDKInit.init(this.context.getApplicationContext(), initConfig)
      .then(() => {
        RTCXLogger.i('SDKInit', 'SDK初始化完成')
      })
      .catch((error: Error) => {
        RTCXLogger.e('SDKInit', `SDK初始化失败：${error.message}`)
      })
  }
}

初始化说明

appKeyConfig 与 specialAppKeyConfig 至少设置一个，否则 init 会抛出异常。
init 只能调用一次，重复调用会抛出异常；需要重新初始化时先调用 uninit。
初始化配置会写入加密本地存储，下次启动调用 init 时可直接复用缓存的国家、regionId 等信息。
uninit 会清空 SDK 本地缓存，包括初始化配置与登录态，之后需要重新调用 init 并重新登录。
当前 SDK 仅支持简体中文（zh_CN），未提供语言设置接口。

SDK初始化完成回调

通用版的初始化结果通过 init 返回的 Promise 获取，then 表示初始化完成，可以开始调用其他接口：

RTCXSDKInit.init(this.context.getApplicationContext(), initConfig)
  .then(() => {
    // 初始化完成，可进行自动登录等操作
  })
  .catch((error: Error) => {
    // 初始化失败
  })

同时接入专属版时，专属版初始化结果通过 InitConfig.specialSdkInitFinishedCallback 回调返回，详见专属版SDK初始化。

全量私有化

全量私有化是将通用版相关服务全量部署在客户提供的私有化环境，AppSDK 与通用版是同一套。

区别在于，SDK 初始化时除设置必要的 appKey 和 appSecret 之外，还需要额外设置数据中心协议、数据中心域名（以及私有化信令域名），其他接口调用与通用版均保持一致。

import { RTCXSDKInitTypes, RTCXCommonTypes } from 'rtcxsdk'

const appKeyConfig = new RTCXSDKInitTypes.AppKeyConfig()
appKeyConfig.appKey = 'your_app_key'
appKeyConfig.appSecret = 'your_app_secret'
// 私有化数据中心，支持携带协议前缀：https://datacenter.example.com
appKeyConfig.dataCenterScheme = RTCXCommonTypes.ServerSchemeEnum.HTTPS
appKeyConfig.dataCenterDomain = 'datacenter.example.com'
// 私有化信令域名
appKeyConfig.signalingScheme = RTCXCommonTypes.ServerSchemeEnum.WSS
appKeyConfig.signalingDomain = 'sig.example.com:9824'

const initConfig = new RTCXSDKInitTypes.InitConfig()
initConfig.appKeyConfig = appKeyConfig

await RTCXSDKInit.init(this.context.getApplicationContext(), initConfig)

设置国家

AIRTC 的云端服务为多区域部署，根据初始化时 regionType 的取值，来判断是否需要在初始化时设置国家：

如果 App 运行在中国大陆地区，需要在 SDK 初始化时设置 regionType = REGION_CHINA_ONLY；
如果 App 运行在中国大陆以外地区，需要在 SDK 初始化时设置 regionType = REGION_ALL，并设置国家。

参数取值	是否需要设置国家
`REGION_CHINA_ONLY`	不需要，SDK 初始化时会自动使用中国大陆
`REGION_ALL`	需要特别说明：首次启动时如果未设置过国家，SDK 初始化不会自动解析网关域名，必须先调用 `setCountry` 设置国家，才能调用SDK的其他接口

注意

中国大陆与海外同时接入时需要在控制台【中国数据中心】与【海外数据中心】分别创建两个不同的应用，在 SDK 初始化时，国内版使用国内 appKey 和 appSecret，海外版使用海外的 appKey 和 appSecret。
切换 appKey、appSecret 或 regionType 重新初始化 SDK 之前，请先调用 RTCXSDKInit.uninit() 清除本地缓存，否则可能使用旧区域的 regionId 导致 SDK 初始化失败。

国家信息

/**
 * 国家
 * @public
 */
export declare class Country {
  /** 区号 */
  code: string;
  /** 拼音 */
  pinyin: string;
  /** 三位字母标识 */
  isoCode: string;
  /** 地区名称 */
  areaName: string;
  /** 两位字母标识 */
  domainAbbreviation: string;

  constructor(code: string, pinyin: string, isoCode: string, areaName: string, domainAbbreviation: string);
}

设置国家

/**
 * 设置用户所在国家或区域
 * @public
 */
export declare function setCountry(country: Country): Promise<void>;

const country = new RTCXCommonTypes.Country('1', 'MeiGuo', 'USA', '美国', 'US')
RTCXSDKInit.setCountry(country)
  .then(() => {
    RTCXLogger.i('SDKInit', '设置国家成功')
  })
  .catch((error: Error) => {
    RTCXLogger.e('SDKInit', `设置国家失败：${error.message}`)
  })

setCountry 会向数据中心查询网关与 STUN 地址，设置成功后国家会被缓存，后续启动 init 时会自动使用缓存的国家解析网关域名。

信息

regionType 为 REGION_CHINA_ONLY 时，SDK 已自动使用中国大陆，此时调用 setCountry 传入其他国家会设置失败。

获取已设置的国家

/**
 * 获取用户所在国家或区域
 * @public
 */
export declare function getCountry(): Country | undefined;

const country = RTCXSDKInit.getCountry()

日志控制

为了方便分析问题，SDK 会将日志输出到控制台，也可以通过日志回调交给上层处理。建议在 SDK 初始化之前设置，方便输出完整日志。

日志开关

通过 InitConfig.debug 控制，init 会最先应用该开关。开启时会输出调试日志，关闭时不输出日志。

initConfig.debug = true

日志等级

RTCXLogger 基于 hilog 输出日志，默认等级为 INFO，可通过 setLogLevel 调整：

import { hilog } from '@kit.PerformanceAnalysisKit';
import { RTCXLogger } from 'rtcxsdk'

RTCXLogger.setLogLevel(hilog.LogLevel.DEBUG)

日志回调

如果需要自行搜集、存储日志，可以设置自定义日志处理对象。设置后 SDK 日志不再输出到 hilog，全部交给该对象处理：

RTCXLogger.logger = {
  debug: (tag: string, msg: string) => {
  },
  info: (tag: string, msg: string) => {
  },
  warn: (tag: string, msg: string) => {
  },
  error: (tag: string, msg: string, error?: Error) => {
  }
}

SDK初始化​

接口说明​

配置项​

初始化示例​

初始化说明​

SDK初始化完成回调​

全量私有化​

设置国家​

日志控制​

SDK初始化

接口说明

配置项

初始化示例

初始化说明

SDK初始化完成回调

全量私有化

设置国家

日志控制