更新记录

1.0.0（2026-08-12）

• 首次发布。
• 支持 uni-app Vue 2 和 uni-app x 项目。
• 支持 Android 5.0 及以上系统、iOS 12.0 及以上系统。
• 支持 Meta/Facebook SDK 初始化、登录、退出登录和当前登录信息查询。
• 支持 Facebook 链接分享，以及分享成功、失败和用户取消回调。
• 支持 Meta App Events 事件记录、用户 ID 设置和事件相关隐私开关。
• 支持 Deferred App Link、冷启动 Deep Link 查询和运行时 Deep Link 监听。
• 支持插件调试日志开关。
• 提供完整的 UTS 类型定义、错误码和中文使用文档。
• 修复 uni-app Android 中取消分享后未触发 9020201 回调的问题。

平台兼容性

uni-app(5.23)

uni-app x(5.23)

hans-meta

hans-meta 是面向 uni-app 和 uni-app x 的 Meta/Facebook 原生 SDK UTS 插件，提供登录、退出登录、Token 查询、链接分享、App Events、Deferred App Link 和 Deep Link 能力。

平台支持

系统要求：

• 原生混编至少需要 HBuilderX 4.25；建议使用已验证的 HBuilderX 5.23 或更高兼容版本。
• Android 5.0（API 21）及以上。
• iOS 12.0 及以上。
• Android 使用 Meta SDK 18.2.3。
• iOS 使用 Meta SDK 18.0.3。
• Android 和 iOS 都需要包含插件原生依赖及宿主配置的自定义基座或正式安装包。

安装

将插件放入项目：

uni_modules/hans-meta

应用代码只能从插件根路径导入，不要直接导入 utssdk 下的平台文件：

import {
  initMeta,
  login,
  logout,
  getCurrentAccessToken,
  shareLink,
  logEvent,
  flushEvents,
  fetchDeferredAppLink,
} from '@/uni_modules/hans-meta'

同一套根路径导入方式适用于普通 uni-app JavaScript 页面和 uni-app x UTS 页面。

在 UTS 代码中，公开类型也从插件根路径导入：

import {
  initMeta,
  MetaFail,
  MetaInitOptions,
  MetaInitResult,
} from '@/uni_modules/hans-meta'

const options: MetaInitOptions = {
  success: (res: MetaInitResult): void => {
    console.log(res.initialized)
  },
  fail: (err: MetaFail): void => {
    console.error(err.errCode, err.errMsg)
  },
}

initMeta(options)

使用前配置

Meta 开发者后台

先在 Meta 开发者后台创建应用，并准备：

• Meta App ID。
• Meta Client Token。
• Android Package Name 和签名 Key Hash。
• iOS Bundle ID。
• Facebook Login、分享及 App Links 所需的产品配置。

Client Token 可以放在客户端初始化配置中，但不要把 Meta App Secret 或登录后的 Access Token 写入源码、文档或日志。

Android

修改以下文件中的示例配置：

utssdk/app-android/res/values/strings.xml
utssdk/app-android/AndroidManifest.xml

需要替换：

• facebook_app_id：Meta App ID。
• fb<APP_ID>：Facebook 登录回调 URL Scheme。

还需要在 Meta 开发者后台填写最终安装包对应的：

• Package Name。
• Main Activity。
• 签名证书 Key Hash。

更换本地证书、云端证书或商店 App Signing 证书后，必须重新计算并添加对应 Key Hash。

如果使用 Android App Links，还要在宿主 Activity 中配置真实域名的 intent-filter，并在域名部署 assetlinks.json。不要保留插件模板中的 example.com。

iOS

修改：

utssdk/app-ios/Info.plist

需要替换：

• FacebookAppID：Meta App ID。
• FacebookDisplayName：Meta 应用显示名称。
• fb<APP_ID>：Facebook 登录回调 URL Scheme。

同时在 Meta 开发者后台配置最终应用的 Bundle ID。

如果使用 Universal Links，还要修改：

utssdk/app-ios/UTS.entitlements

把 applinks:example.com 替换成真实域名，并在域名部署 apple-app-site-association。不使用 Universal Links 时应移除示例域名配置。

Client Token

建议把 Client Token 放在业务项目的本地配置中，再传给 initMeta()：

// meta.local-config.js 或 meta.local-config.uts
export const META_CLIENT_TOKEN = 'your-meta-client-token'

本地配置文件是否提交到版本库，由项目自己的安全策略决定。

快速开始

1. 初始化

所有登录、分享、事件和 Deferred App Link API 都应在初始化成功后调用。

import { initMeta } from '@/uni_modules/hans-meta'
import { META_CLIENT_TOKEN } from '@/meta.local-config'

initMeta({
  appId: 'your-meta-app-id',
  clientToken: META_CLIENT_TOKEN,
  autoLogAppEventsEnabled: false,
  advertiserIDCollectionEnabled: false,
  eventDataUsageLimited: true,
  debug: false,
  success(res) {
    console.log('Meta SDK initialized', res)
  },
  fail(err) {
    console.error('Meta SDK init failed', err)
  },
})

appId 和原生配置中的 App ID 应保持一致。插件不允许在同一进程中用不同 App ID 重复初始化。

2. 登录、查询 Token 和退出登录

import {
  login,
  logout,
  getCurrentAccessToken,
} from '@/uni_modules/hans-meta'

login({
  permissions: ['public_profile'],
  success(res) {
    // res 可能包含 accessToken、authenticationToken 和 userId。
    // 不要把完整 Token 输出到日志或上传到非受信服务。
    console.log('permissions', res.permissions)
  },
  fail(err) {
    if (err.errCode === 9020101) {
      console.log('User cancelled login')
      return
    }
    console.error('Facebook login failed', err)
  },
})

const token = getCurrentAccessToken()
if (token != null) {
  console.log('Facebook session exists')
}

logout()

说明：

• permissions 默认值为 ['public_profile']。
• loginBehavior、tracking 和 nonce 是预留参数，当前版本建议不传。
• 用户取消登录时调用 fail 和 complete，错误码为 9020101。
• getCurrentAccessToken() 应在初始化成功后调用；没有有效会话时返回 null。

3. 分享链接

import { shareLink } from '@/uni_modules/hans-meta'

shareLink({
  url: 'https://example.com/article/1',
  quote: '推荐阅读',
  hashtag: '#example',
  dialogMode: 'automatic',
  success(res) {
    console.log('Share completed', res.completed)
  },
  fail(err) {
    if (err.errCode === 9020201) {
      console.log('User cancelled sharing')
      return
    }
    console.error('Facebook share failed', err)
  },
})

说明：

• url 必须是包含 scheme 的有效 URL。
• Android 当前使用 Meta SDK 的 automatic 模式。
• iOS 支持 automatic、native、browser、web、feedBrowser 和 feedWeb；未知值按 automatic 处理。
• 用户取消分享时调用 fail 和 complete，错误码为 9020201。
• postId 由 Meta SDK 决定，很多分享场景不会返回该字段。

4. App Events

import {
  logEvent,
  flushEvents,
  setUserId,
  setAutoLogAppEventsEnabled,
  setAdvertiserIDCollectionEnabled,
  setEventDataUsageLimited,
} from '@/uni_modules/hans-meta'

setUserId('business-user-id')
setAutoLogAppEventsEnabled(false)
setAdvertiserIDCollectionEnabled(false)
setEventDataUsageLimited(true)

logEvent({
  name: 'purchase_completed',
  valueToSum: 99.9,
  parameters: {
    currency: 'CNY',
    order_type: 'subscription',
  },
  success() {
    flushEvents({
      success(res) {
        console.log('Flush requested', res.ok)
      },
    })
  },
  fail(err) {
    console.error('Event failed', err)
  },
})

// 解除业务用户关联
setUserId(null)

parameters 当前应只包含字符串、数字和布尔值；不要传嵌套对象或数组。logEvent 的成功回调只表示事件已经提交给本地 SDK，不代表 Meta 服务端已经接收或完成归因。

flushEvents() 当前存在平台差异：

• iOS 会调用 Meta SDK 的事件队列刷新方法。
• Android 当前仅返回 { ok: true } 并记录调试日志，不会强制刷新原生事件队列。

因此不要把 flushEvents() 的成功回调当作事件上传成功凭证。

广告标识采集、自动事件和用户标识必须根据应用隐私政策、用户授权状态及上架地区法规决定是否启用。

5. Deferred App Link

import { fetchDeferredAppLink } from '@/uni_modules/hans-meta'

fetchDeferredAppLink({
  success(res) {
    if (res.found && res.url) {
      console.log('Deferred App Link', res.url)
    }
  },
  fail(err) {
    console.error('Deferred App Link failed', err)
  },
})

6. 启动链接和运行时 Deep Link

import {
  getInitialDeepLink,
  onDeepLink,
  offDeepLink,
} from '@/uni_modules/hans-meta'

const initialLink = getInitialDeepLink()
if (initialLink != null) {
  console.log('Initial deep link', initialLink.url)
}

const listener = (res) => {
  console.log('Deep link received', res.url)
}

onDeepLink(listener)

// 页面或应用销毁时移除同一个监听函数
offDeepLink(listener)

// 不传参数会移除当前进程中注册的全部业务监听
// offDeepLink()

冷启动链接可通过 getInitialDeepLink() 读取。运行期间的 onDeepLink() 还要求宿主把 Android onNewIntent、iOS Open URL / Universal Link 生命周期事件转发给插件原生处理器；插件当前没有公开手动转发 API。如果宿主没有完成这部分原生生命周期接线，onDeepLink() 不会自动收到运行时链接。

7. 调试日志

import {
  setDebugLogEnabled,
  isDebugLogEnabled,
} from '@/uni_modules/hans-meta'

setDebugLogEnabled(true)
console.log('Meta debug enabled:', isDebugLogEnabled())

生产环境建议关闭调试日志。

回调约定

异步 API 使用 uni-app 风格的三个可选回调：

• success：调用成功。
• fail：调用失败或用户取消。
• complete：无论成功还是失败都会调用，参数是成功结果或 MetaFail。

取消登录和取消分享属于 fail，不是异常崩溃；业务可以通过 errCode 单独处理。

API 列表

类型定义

以下为插件当前公开类型。UTSJSONObject、IUniError 和 any 是 uni-app/UTS 基础类型。

type MetaErrorCode =
  9020001 | 9020002 | 9020003 |
  9020101 | 9020102 | 9020103 |
  9020201 | 9020202 |
  9020301 | 9020302 |
  9020401 |
  9029001

interface MetaFail extends IUniError {
  errCode: MetaErrorCode
  platform: string
  nativeCode?: string
  metaExtra?: string
}

type MetaEmptyResult = {
  ok: boolean
}

type MetaInitOptions = {
  appId?: string
  clientToken?: string
  autoLogAppEventsEnabled?: boolean
  advertiserIDCollectionEnabled?: boolean
  eventDataUsageLimited?: boolean
  debug?: boolean
  success?: (res: MetaInitResult) => void
  fail?: (err: MetaFail) => void
  complete?: (res: any) => void
}

type MetaInitResult = {
  initialized: boolean
  sdkVersion?: string
  appId?: string
  staticConfigValid: boolean
}

type MetaLoginOptions = {
  permissions?: string[]
  loginBehavior?: string
  tracking?: string
  nonce?: string
  success?: (res: MetaLoginResult) => void
  fail?: (err: MetaFail) => void
  complete?: (res: any) => void
}

type MetaLoginResult = {
  accessToken?: string
  authenticationToken?: string
  tokenType?: string
  userId?: string
  expiresAt?: number
  permissions: string[]
  declinedPermissions: string[]
  isLimitedLogin?: boolean
}

type MetaShareLinkOptions = {
  url: string
  quote?: string
  hashtag?: string
  dialogMode?: string
  success?: (res: MetaShareResult) => void
  fail?: (err: MetaFail) => void
  complete?: (res: any) => void
}

type MetaShareResult = {
  postId?: string
  completed?: boolean
  cancelled?: boolean
  raw?: UTSJSONObject
}

type MetaLogEventOptions = {
  name: string
  valueToSum?: number
  parameters?: UTSJSONObject
  success?: (res: MetaEmptyResult) => void
  fail?: (err: MetaFail) => void
  complete?: (res: any) => void
}

type MetaFlushEventsOptions = {
  success?: (res: MetaEmptyResult) => void
  fail?: (err: MetaFail) => void
  complete?: (res: any) => void
}

type MetaDeepLinkResult = {
  url: string
  source: string
  isDeferred?: boolean
  extras?: UTSJSONObject
}

type MetaDeferredAppLinkOptions = {
  success?: (res: MetaDeferredAppLinkResult) => void
  fail?: (err: MetaFail) => void
  complete?: (res: any) => void
}

type MetaDeferredAppLinkResult = {
  found: boolean
  url?: string
  source: string
  extras?: UTSJSONObject
}

type MetaDeepLinkCallback = (res: MetaDeepLinkResult) => void

expiresAt 是 Unix 毫秒时间戳。

错误码

MetaFail 还可能包含：

• platform：app-android、app-ios 或其他平台标识。
• nativeCode：原生错误分类，例如 CANCELLED、INVALID_URL。
• metaExtra：可选的原生附加信息。

常见问题

标准基座中找不到 Meta SDK 类

插件包含 Maven 和 CocoaPods 原生依赖。请重新制作自定义基座，或安装包含该插件的正式包；仅同步前端资源不会把新的原生依赖加入已有基座。

登录无法回到应用

依次检查：

• Meta App ID 是否与原生配置一致。
• Android/iOS 的 fb<APP_ID> URL Scheme 是否正确。
• Android Package Name、Main Activity 和 Key Hash 是否匹配当前安装包。
• iOS Bundle ID 是否与 Meta 开发者后台一致。
• 当前 Meta 应用模式和测试账号是否允许登录。

分享成功但没有 postId

postId 是可选字段，是否返回由 Meta SDK、分享方式、应用权限和用户行为共同决定。业务应以 success 回调为完成信号，不应依赖 postId 一定存在。

如何处理 Token

不要打印或持久化完整 accessToken、authenticationToken 和 userId。如果服务端需要验证登录状态，应通过 HTTPS 发送到自己的受信后端，并按 Meta 官方安全要求进行校验和存储。