更新记录

1.2.7（2026-08-24）

调整插件信息

1.2.6（2026-08-24）

支持 iOS 平台通过 publishMedia 和 shareMediaToIm 的 filePaths 传入系统相册 PHAsset.localIdentifier，可直接提交指定的相册媒体；未传时仍打开系统相册选择器。

1.2.5（2026-08-17）

修复 iOS平台投稿崩溃问题

平台兼容性

uni-app(5.08)

uni-app x(5.08)

tt-douyin-open

抖音开放平台 UTS 原生插件，支持 uni-app x 与 uni-app。提供 初始化（register）、授权登录（login）、媒体投稿（publishMedia） 与私信分享。

推荐 API：使用 publishMedia() 投稿，或使用 shareMediaToIm()、shareLinkToIm()、shareMiniAppToIm() 分享私信。旧 share() 保留兼容，但新项目不应再组合 scene、contentType、useInternalPicker 等历史字段。业务通过 getTTDouyinSDK() 取单例。

📚 官方文档：抖音开放平台 - 移动应用

目录

• 版本信息
• 接入前必读
• 环境配置
• 快速开始
• 常用能力示例
• API 参考
• 平台差异
• 错误码
• 常见问题

版本信息

接入前必读

• 仅支持 App 真机环境；请使用自定义基座或云打包后的 App，浏览器和小程序环境不能调用本插件。
• 必须先在抖音开放平台创建移动应用，并使 ClientKey、Android 包名与签名、iOS Bundle ID、鸿蒙应用信息和当前安装包一致。
• 调用 login、投稿或私信前必须先成功调用 register；iOS 还必须配置 ClientKey URL Scheme 和相册权限。
• 投稿、私信、小程序、音乐、POI、贴纸等能力受开放平台 Scope、业务资质和抖音客户端版本限制；首次联调仅使用基础媒体投稿，不要传占位业务数据。
• success / fail 是抖音完成或取消操作并返回应用后的结果，不表示 share() 调用同步完成。

环境配置

前置条件

1. 在 抖音开放平台 创建移动应用，获取 ClientKey（代码里 register 的 appid 传此值）。
2. 按平台在开放平台配置 包名、签名（Android）、Bundle ID（iOS）、鸿蒙应用信息等。

iOS

1. 编辑 uni_modules/tt-douyin-open/utssdk/app-ios/Info.plist：DouyinAppID、URL Types 的 CFBundleURLSchemes 填写 ClientKey；LSApplicationQueriesSchemes 含 douyinopensdk、snssdk1128 等（以插件内模板为准）。
2. 使用媒体私信分享或投稿前，需在最终 App 的 Info.plist 添加相册权限：NSPhotoLibraryUsageDescription。
3. 在应用 生命周期 中接入插件 Hook（TTDouyinSDKHookProxy），保证抖音 SDK 能收到 冷启动与 URL 回调（与 uni 工程 manifest 配置一致即可）。

Android

在开放平台配置 签名与包名；工程需能拉取插件 config.json 中的 AwemeOpenSDK Maven 仓库。其余按 抖音 Android 集成文档 配置 FileProvider、回调 Activity 等。

HarmonyOS

1. ohpm：项目根 harmony-configs/.ohpmrc 需能访问字节仓库，例如：

registry=https://ohpm.byted.org/repos/ohpm/,http://artifact.bytedance.com/repository/byted-ohpm/

2. harmony-configs/entry/src/main/module.json5：querySchemes 包含抖音相关 scheme；skills / uris（https applinks） 与代码里 redirectUri 一致；声明 网络权限。完整模板请以 抖音鸿蒙 / OpenHarmony 官方说明 为准。

快速开始

1. 导入插件

uni-app x

import * as douyinSDK from "@/uni_modules/tt-douyin-open";

export default {
  data() {
    return {
      douyin: null as douyinSDK.TTDouyinSDK | null,
    };
  },
  onLoad() {
    this.douyin = douyinSDK.getTTDouyinSDK();
    this.initDouyinSDK();
  },
  methods: {
    initDouyinSDK() {
      /* 见下方「2. 初始化 SDK」 */
    },
  },
};

uni-app

import * as douyinSDK from "@/uni_modules/tt-douyin-open";

export default {
  data() {
    return { douyin: null };
  },
  onLoad() {
    this.douyin = douyinSDK.getTTDouyinSDK();
    this.initDouyinSDK();
  },
  methods: {
    initDouyinSDK() {
      /* 见下方「2. 初始化 SDK」 */
    },
  },
};

2. 初始化 SDK

uni-app x

initDouyinSDK() {
  if (this.douyin == null) return;
  this.douyin.register({
    appid: "你的ClientKey",
    success: () => {
      console.log("抖音初始化成功");
    },
    fail: (err) => {
      console.error("抖音初始化失败", err);
    },
  } as douyinSDK.TTDouyinRegisterOptions);
}

uni-app

initDouyinSDK() {
  if (!this.douyin) return;
  this.douyin.register({
    appid: "你的ClientKey",
    success: () => {
      console.log("抖音初始化成功");
    },
    fail: (err) => {
      console.error("抖音初始化失败", err);
    },
  });
}

API 参考

所有 API 均通过 getTTDouyinSDK() 返回的单例调用。register 成功前调用 login 或 share 会失败并返回 errCode: 101。

getTTDouyinSDK()

const sdk = douyinSDK.getTTDouyinSDK();

无入参，返回 TTDouyinSDK。建议在页面或应用启动后保存该实例，并先调用 register。

register(options)

sdk.register(options: TTDouyinRegisterOptions): void

login(options)

sdk.login(options: TTDouyinLoginOptions): void

publishMedia(options)（推荐）

sdk.publishMedia(options: TTDouyinPublishMediaOptions): void

固定执行媒体投稿，不需要传 scene: 'publish' 或 contentType: 'media'。

iOS 基础投稿

sdk.publishMedia({
  mediaType: 'video',
  shareId: 'publish_' + Date.now(),
  caption: {
    text: '我的精彩视频',
    hashtagsJson: '[{"name":"美好生活","start":0}]',
  },
  publish: { targetPage: 'edit' },
  success: () => console.log('抖音已接受投稿请求'),
  fail: (err) => console.error(err),
} as douyinSDK.TTDouyinPublishMediaOptions);

iOS 可通过其他原生插件取得 PHAsset.localIdentifier 后传入 filePaths，插件会直接提交给抖音 SDK；不要传本地文件路径。未传时插件会自行打开系统相册。用户从抖音取消后若 SDK 未返回完成事件，插件会在应用重新激活后以 fail / complete 结束本次请求，随后可发起下一次投稿。

Android / 鸿蒙基础投稿

sdk.publishMedia({
  mediaType: 'video',
  filePaths: ['/可读取的视频路径或content-uri'],
  harmony: {
    redirectUri: 'https://你的域名/抖音回调路径',
  },
  fail: (err) => console.error(err),
} as douyinSDK.TTDouyinPublishMediaOptions);

Android 忽略 harmony；鸿蒙必须提供其中的 redirectUri。实际跨端项目应按平台传入各自的媒体路径和鸿蒙配置。

所有平台的复杂嵌套数组均推荐使用 JSON 字符串：caption.hashtagsJson、ios/android.mentionsJson、ios/android.stickersJson，分别对应 TTDouyinPublishHashtag[]、TTDouyinPublishMention[]、TTDouyinSticker[]。不要同时传同名数组字段；其中 iOS 必须使用 JSON 字符串，以避开 UTS 嵌套数组桥接问题。

私信分享（推荐）

shareMediaToIm(options)、shareLinkToIm(options)、shareMiniAppToIm(options) 分别对应媒体、链接、小程序卡片，避免旧接口中 scene 与 contentType 的非法组合。媒体参数的 filePaths 规则与投稿相同：iOS 可传 PHAsset.localIdentifier，不传则打开相册；Android 必传；鸿蒙当前明确不支持私信分享。

share(options)（兼容接口）

sdk.share(options: TTDouyinShareOptions): void

Options

TTDouyinShareMediaContent

TTDouyinShareLinkContentIM

仅 scene: 'im' 且 contentType: 'link' 使用，以下字段均必传。

TTDouyinShareMicroAppContentIM

仅 scene: 'im' 且 contentType: 'microApp' 使用。

TTDouyinShareTitle 与 TTDouyinMusicParam

进阶内容类型

以下类型全部可选。它们需要开放平台已开通对应能力，字段必须是真实数据；不要用占位值验证基础投稿。

返回与错误

register 成功时返回空对象；login 成功时返回 { code, state }；share 成功时返回空对象。失败回调统一为 IUniError，常用字段为 errCode、errMsg；抖音 SDK 原始错误可从 cause.code 和 cause.message 获取。

常用能力示例

抖音授权登录

流程：客户端拿到 code → 服务端用 code 换 access_token → 再取用户信息（见 开放平台服务端文档）。

uni-app x 示例

this.douyin!.login({
  state: String(Date.now()),
  permissions: ["user_info"],
  redirectUri: "https://你的域名/你的path",
  callerLocalEntry: "EntryAbility",
  success: (res) => {
    console.log(res.code, res.state);
  },
  fail: (err) => {
    console.error(err);
  },
} as douyinSDK.TTDouyinLoginOptions);

uni-app 示例

this.douyin.login({
  state: String(Date.now()),
  permissions: ["user_info"],
  redirectUri: "https://你的域名/你的path",
  callerLocalEntry: "EntryAbility",
  success: (res) => {
    uni.request({
      url: "https://你的服务端/api/douyin/login",
      method: "POST",
      data: { code: res.code, state: res.state },
    });
  },
  fail: (err) => {
    uni.showToast({ title: "授权失败", icon: "none" });
  },
});

抖音分享

统一调用：this.douyin.share(options)，options 类型为 TTDouyinShareOptions。

能力概览：

• 投稿发布：三端均支持通过 scene: 'publish' + contentType: 'media' 走抖音 投稿 / 发布 流程（标题、音乐、贴纸、publishMode（feed / forwardDaily）、publishTargetPage（edit / publish）、鸿蒙 harmonyLandingPage（edit / record）等以 interface.uts 为准）。
• 私信分享：Android / iOS 支持 scene: 'im'（media / link / microApp）；鸿蒙 当前不支持 im。

完整必传条件、默认值和数据类型见上方 API 参考；下表汇总投稿媒体字段的组合限制。

参数必填与适用条件

调用任何分享能力前必须先成功调用 register({ appid })，且开放平台中的应用信息必须与当前安装包一致。下表中的“必传”表示插件调用所需；抖音客户端版本、开放平台 Scope 和业务资质仍可能限制最终能力。

平台行为简述：

以下为 投稿发布、私信分享 分端示例；uni-app 与 uni-app x 仅差类型断言，逻辑相同。

投稿发布：Android / iOS（uni-app x）

Android：mediaContent.filePaths 必填（本地绝对路径或 content://，需满足 FileProvider 与抖音可读要求）。
iOS：投稿会先走 系统相册选择；mediaContent 主要配 mediaType、标题、音乐、贴纸 等，其它字段见 interface.uts。

// Android：必须提供 filePaths
this.douyin!.share({
  scene: "publish",
  contentType: "media",
  state: "可选",
  publishMode: "feed",
  publishTargetPage: "edit",
  mediaContent: {
    filePaths: ["/绝对路径/demo.jpg"],
    mediaType: "image",
    title: { title: "作品标题" },
  },
  success: () => {},
  fail: (e) => {
    console.error(e);
  },
} as douyinSDK.TTDouyinShareOptions);

// iOS：以相册选图为主，filePaths 等见 interface.uts
this.douyin!.share({
  scene: "publish",
  contentType: "media",
  state: "可选",
  publishMode: "feed",
  publishTargetPage: "edit",
  mediaContent: {
    mediaType: "image",
    title: { title: "作品标题" },
  },
  success: () => {},
  fail: (e) => {
    console.error(e);
  },
} as douyinSDK.TTDouyinShareOptions);

投稿发布：Android / iOS（uni-app）

// Android
this.douyin.share({
  scene: "publish",
  contentType: "media",
  publishMode: "feed",
  publishTargetPage: "edit",
  mediaContent: {
    filePaths: ["/绝对路径/demo.jpg"],
    mediaType: "image",
    title: { title: "作品标题" },
  },
  success: () => {},
  fail: () => {},
});

// iOS
this.douyin.share({
  scene: "publish",
  contentType: "media",
  publishMode: "feed",
  publishTargetPage: "edit",
  mediaContent: {
    mediaType: "image",
    title: { title: "作品标题" },
  },
  success: () => {},
  fail: () => {},
});

私信分享：Android / iOS（uni-app x）

仅 scene: 'im'，鸿蒙不支持。示例为 发单图/单视频给好友；链接、小程序见 linkContent / microAppContent。

this.douyin!.share({
  scene: "im",
  contentType: "media",
  state: "可选",
  mediaContent: {
    filePaths: ["/绝对路径/单张图或单个视频"],
    mediaType: "image",
  },
  success: () => {},
  fail: (e) => {
    console.error(e);
  },
} as douyinSDK.TTDouyinShareOptions);

私信分享：Android / iOS（uni-app）

this.douyin.share({
  scene: "im",
  contentType: "media",
  mediaContent: {
    filePaths: ["/绝对路径/单张图或单个视频"],
    mediaType: "image",
  },
  success: () => {},
  fail: () => {},
});

投稿发布：鸿蒙（uni-app x）

this.douyin!.share({
  scene: "publish",
  contentType: "media",
  state: "业务或开放平台 ShareID",
  redirectUri: "https://你的域名/applink路径",
  callerLocalEntry: "EntryAbility",
  harmonyLandingPage: "edit",
  mediaContent: {
    filePaths: ["/本地绝对路径/demo.jpg"],
    mediaType: "image",
  },
  success: () => {},
  fail: (e) => {
    console.error(e);
  },
} as douyinSDK.TTDouyinShareOptions);

投稿发布：鸿蒙（uni-app）

this.douyin.share({
  scene: "publish",
  contentType: "media",
  state: "业务或开放平台 ShareID",
  redirectUri: "https://你的域名/applink路径",
  callerLocalEntry: "EntryAbility",
  harmonyLandingPage: "edit",
  mediaContent: {
    filePaths: ["/本地绝对路径/demo.jpg"],
    mediaType: "image",
  },
  success: () => {
    uni.showToast({ title: "已发起分享", icon: "none" });
  },
  fail: (e) => {
    uni.showToast({ title: (e && e.errMsg) || "分享失败", icon: "none" });
  },
});

mediaType 为 mix 时：filePaths 需多个路径，具体条数与能力以抖音客户端与开放平台为准。

平台差异

错误码

常见 errCode（详见 utssdk/unierror.uts 中 TTDouyinSDKErrors）：

建议在 fail 回调中保留完整错误对象。errMsg 适合直接展示或记录，排障日志可同时记录 errCode、errMsg、cause.code、cause.message：

fail: (err) => {
  console.error('抖音 SDK 调用失败', err);
  console.error(err.errCode, err.errMsg, err.cause?.code, err.cause?.message);
}

常见问题

1. 找不到插件方法
   使用 自定义基座 或正式包，不要用未包含本插件的标准基座。

2. iOS 登录无响应
   检查 ClientKey、URL Scheme。

3. Android 授权或分享无回调
   核对开放平台 签名、包名 及文档要求的 回调 Activity 配置。

4. 鸿蒙 ohpm 安装失败（ECONNRESET 等）
   多为本机访问 ohpm.byted.org 网络问题，需换网络、代理或放行域名；日志里 CaseSensitive 相关 DEBUG 可忽略。

5. 鸿蒙提示 redirectUri
   与 module.json5 中 applinks（uris） 及开放平台配置保持一致。

更多排障请对照 抖音开放平台文档。

祝您开发愉快！ 🎉