更新记录

1.0.0（2026-04-09）

支持 安卓与iOS平台的ins授权登录与分享

平台兼容性

uni-app(4.86)

uni-app x(4.86)

tt-instagram-opensdk

🚀 Instagram 登录与分享插件，为 uni-app x 与 uni-app 提供 Instagram 授权登录、分享到动态（Feed）、分享到快拍（Stories）能力。

📖 目录

• SDK版本信息
• 环境配置
  • 前置条件
  • iOS 平台配置
  • Android 平台配置
• 快速开始
• 功能介绍
  • Instagram 授权登录
  • 分享到动态（Feed）
  • 分享到快拍（Stories）
• 错误处理
• 常见问题
• 参考文档
• 技术支持

SDK版本信息

功能支持矩阵

📚 推荐阅读：Instagram 开放平台 - 分享到动态 · 分享到快拍

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件原生方法（与微博、飞书等 UTS 插件一致）。

⚠️ 登录必须配置正确的回调地址：redirectUrl 须与 Instagram / Meta 开发者后台登记的 Redirect URI 一致，且宿主应用能接收该 Scheme 或 Universal Link。

⚠️ 分享成功回调表示「已成功拉起 Instagram 客户端」，不代表用户已在 Instagram 内完成发布。

⚠️ 快拍分享须传入 sourceApplication（Facebook App ID），与官方文档要求一致；未配置时 Instagram 可能提示不支持分享到快拍。

⚠️ 素材路径：imagePath / videoPath 等须为应用可读的本地路径（与 UTSiOS.convert2AbsFullPath / UTSAndroid.convert2AbsFullPath 规则一致）。

环境配置

前置条件

1. 在 Meta / Instagram 开发者平台 创建应用并完成 Instagram 相关配置。
2. 获取 Instagram 应用 App ID（用于 login 的 appId）。
3. 快拍分享需获取 Facebook App ID（用于 shareToStory 的 sourceApplication）。
4. 在后台配置 OAuth 重定向 URI，与代码中 login 的 redirectUrl 完全一致（常见形式：ig{你的InstagramAppId}://authorize，具体以你后台登记为准）。

iOS 平台配置

1. 插件内 config.json（已内置）

uni_modules/tt-instagram-opensdk/utssdk/app-ios/config.json 中已配置：

• LSApplicationQueriesSchemes：instagram、instagram-stories

使用自定义基座或云打包时，会与主应用合并；若需增删 Scheme，直接编辑该文件即可。

2. 登录回调 URL Scheme

须在宿主应用（或 uni-app 打包配置）中注册与 redirectUrl 一致的 URL Types，例如 ig{clientId}://authorize 形式，以便授权完成后回到你的 App。

插件通过 TTInstagramSDKHookProxy 处理 openURL 与 Universal Link（continueUserActivity）；请确保工程未屏蔽相关生命周期。

Android 平台配置

1. 登录 Deep Link

授权完成后浏览器会跳转到你的 redirectUrl。须在宿主 AndroidManifest.xml 的入口 Activity（如 MainActivity）上配置对应 intent-filter（VIEW + BROWSABLE + 与 redirectUrl 匹配的 scheme / host），否则可能收不到 token。

2. 本地文件与 FileProvider

分享到动态 / 快拍使用本地文件 URI 时，需保证宿主已正确配置 FileProvider（与 uni-app 默认模板一致即可），否则 EXTRA_STREAM / Story Intent 可能无法被 Instagram 读取。

快速开始

1. 导入插件

import * as instagram from "@/uni_modules/tt-instagram-opensdk";

2. 获取 SDK 实例

const ins = instagram.getTTInstagramSDK();

登录参数在每次 login 时传入即可；无单独的 register 或「SDK 初始化」步骤，因此也不会出现「SDK 未初始化」类错误码。

功能介绍

Instagram 授权登录

💡 使用 OAuth implicit（response_type=token），授权完成后从回调 URL 的 fragment 中解析 access_token。请勿在客户端长期存储敏感令牌，建议结合服务端换票或自有安全策略。

双端实现差异（与 app-ios / app-android 源码一致）

参数说明

TTInstagramLoginOptions

返回值 TTInstagramLoginSuccess

示例代码

ins.login({
  appId: "您的Instagram应用AppId",
  redirectUrl: "ig您的Instagram应用AppId://authorize",
  scope: "user_profile",
  success: (res) => {
    console.log("✅ Instagram 登录成功", res.accessToken);
  },
  fail: (err) => {
    console.error("❌ Instagram 登录失败", err.errCode, err.errMsg);
    handleInstagramLoginError(err);
  },
  complete: () => {
    console.log("Instagram 登录流程结束");
  }
});

function handleInstagramLoginError(error: any) {
  switch (error.errCode) {
    case 101:
    case 103:
      uni.showToast({ title: error.errMsg || "参数错误", icon: "error" });
      break;
    case 201:
      // 仅 Android：未带回回调 URI，多为用户取消
      console.log("用户取消或未完整授权", error.errMsg);
      break;
    case 202:
      // errMsg 可能为「无法打开Instagram授权页」「Activity不可用」「授权地址无效」或 OAuth 的 error_description
      uni.showToast({ title: error.errMsg || "登录失败", icon: "error" });
      break;
    case 203:
      uni.showToast({ title: error.errMsg || "登录结果解析失败", icon: "error" });
      break;
    default:
      uni.showToast({ title: error.errMsg || "登录失败", icon: "error" });
      break;
  }
}

分享到动态（Feed）

💡 将本地图片或视频传入 Instagram 编辑页；格式与尺寸需符合 官方 Feed 分享说明。

参数说明

TTInstagramShareToFeedOptions

使用示例

// 分享图片到动态
ins.shareToFeed({
  mediaType: "image",
  imagePath: "/static/logo.png",
  caption: "来自 uni-app 的分享",
  success: () => {
    console.log("✅ 已调起 Instagram（动态）");
  },
  fail: (err) => {
    console.error("❌ 分享失败", err);
    uni.showToast({ title: err.errMsg || "分享失败", icon: "error" });
  },
  complete: () => {}
});

// 分享视频到动态
ins.shareToFeed({
  mediaType: "video",
  videoPath: "/path/to/video.mp4",
  caption: "视频分享",
  success: () => {},
  fail: (err) => {},
  complete: () => {}
});

分享到快拍（Stories）

💡 须提供 Facebook App ID 作为 source_application；背景与贴图规则见 官方 Stories 文档。

参数说明

TTInstagramShareToStoryOptions

使用示例

// 背景图 + 可选贴图
ins.shareToStory({
  sourceApplication: "您的FacebookAppId",
  backgroundMediaType: "image",
  backgroundImagePath: "/static/bg.png",
  stickerImagePath: "/static/sticker.png",
  backgroundTopColor: "#33FF33",
  backgroundBottomColor: "#FF00FF",
  success: () => console.log("✅ 已调起 Instagram（快拍）"),
  fail: (err) => console.error("❌ 快拍分享失败", err)
});

// 背景视频
ins.shareToStory({
  sourceApplication: "您的FacebookAppId",
  backgroundMediaType: "video",
  backgroundVideoPath: "/path/to/story.mp4",
  success: () => {},
  fail: (err) => {}
});

错误处理

以下错误码与 utssdk/unierror.uts 及 app-ios/index.uts、app-android/index.uts 中实际 new TTInstagram*FailImpl(...) 的用法一致；未在代码中出现的码已从码表移除（如历史上的 102 / 104 / 305 / 306 / 999）。

错误码说明

TTInstagramLoginFailImpl / TTInstagramShareFailImpl 构造时若传入第二参数 errMsg，以传入文案为准（表中为 Map 内默认文案）。

常见问题

1. 找不到插件方法？

解决方案：使用自定义基座或包含本插件的云打包产物；标准基座不包含 UTS 原生插件。

2. Android 登录无回调？

解决方案：确认 MainActivity（或实际接收深链的 Activity）已配置与 redirectUrl 一致的 intent-filter；授权完成后系统应能把 URI 交给当前 Activity。

3. iOS 登录无回调？

解决方案：检查 URL Scheme 是否与 redirectUrl 一致；确认工程已合并插件 Hook（applicationOpenURL / continueUserActivity）。

4. 快拍提示不支持或失败？

解决方案：确认 sourceApplication 为正确的 Facebook App ID；Instagram 与 Meta 应用后台需完成关联与审核要求（以官方控制台为准）。

5. 分享提示未安装 Instagram？

解决方案：真机安装 Instagram；iOS 需在 LSApplicationQueriesSchemes 中包含 instagram / instagram-stories（插件 config.json 已内置，重新打基座生效）。

参考文档

• Instagram 开放平台 - 分享到动态
• Instagram 开放平台 - 分享到快拍

📞 技术支持

如果在使用过程中遇到问题，请：

1. 查阅上方 常见问题 与 错误处理
2. 参考 Meta / Instagram 开放平台 官方文档（OAuth、分享到动态 / 快拍等）
3. 核对开发者后台配置：appId、redirectUrl 与登记的 Redirect URI 一致；iOS URL Types / Android intent-filter 与 redirectUrl 一致；快拍场景的 Facebook App ID 与后台关联无误
4. 在真机上确认已安装 Instagram 客户端，并尽量使用较新版本

祝您开发愉快！ 🎉