更新记录

1.0.3（2025-12-17）

支持 双端分享功能

1.0.2（2025-12-16）

更新插件信息

1.0.1（2025-11-03）

修复已知问题

平台兼容性

uni-app(4.36)

uni-app x(4.36)

tt-meta-sdk

🚀 专业版 Meta SDK 插件，为 uni-app x & uni-app 提供完整的 Facebook 集成解决方案，包含授权登录、分享等功能

📖 目录

• SDK版本信息
• 环境配置
• 快速开始
• 基础使用
• 功能介绍
  • Facebook 授权登录
  • Facebook 分享
• 错误处理
• 常见问题

SDK版本信息

📚 推荐阅读:

• Facebook iOS 集成文档
• Facebook Android 集成文档

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法
⚠️ 测试前需确保应用已通过 Facebook 开发者平台审核，否则登录可能失败
⚠️ Android: 确保应用签名与 Facebook 开发者平台配置的签名一致
⚠️ 编译报错排查：本插件会定期更新至最新版SDK，某些情况下编译报错可能不是插件不可用，而是本地环境问题或与官方插件冲突，遇到此类情况可通过IM联系我协助解决

环境配置

前置条件

1. 在 Facebook 开发者平台 创建应用
2. 获取 App ID 和 ClientToken
3. 配置应用包名和签名

iOS平台配置

1. 配置 Info.plist

无需在项目根目录添加或修改 Info.plist。请直接编辑插件内的 uni_modules/tt-meta-sdk/utssdk/app-ios/Info.plist，将以下配置项补充为您的实际值：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>fb+AppID</string>
        </array>
      </dict>
    </array>
    <key>LSApplicationQueriesSchemes</key>
    <array>
      <string>fbapi</string>
      <string>fb-messenger-share-api</string>
    </array>
    <key>FacebookAppID</key>
    <string>APP-ID</string>
    <key>FacebookClientToken</key>
    <string>CLIENT-TOKEN</string>
    <key>FacebookDisplayName</key>
    <string>APP-NAME</string>
  </dict>
</plist>

配置说明：

• fb+AppID: 将 +AppID 替换为您的实际 Facebook App ID，例如 fb123456789
• APP-ID: 替换为您的 Facebook App ID
• CLIENT-TOKEN: 替换为您的 Facebook Client Token
• APP-NAME: 替换为您的应用名称

Android平台配置

1. 配置 AndroidManifest.xml

无需在项目根目录修改配置。请直接编辑插件内的 uni_modules/tt-meta-sdk/utssdk/app-android/AndroidManifest.xml，将以下配置项补充为您的实际值：

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools"
    package="uts.sdk.modules.ttMetaSDK">
    <uses-permission android:name="android.permission.INTERNET" />
    <queries>
        <provider android:authorities="com.facebook.katana.provider.PlatformProvider" />
    </queries>
    <application>
       <meta-data android:name="com.facebook.sdk.ApplicationId" android:value="此处填写您的FacebookAppId"/>
       <meta-data android:name="com.facebook.sdk.ClientToken" android:value="此处填写您的ClientToken"/>

        <activity android:name="com.facebook.FacebookActivity"
            android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation" />
        <activity android:name="com.facebook.CustomTabActivity" android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="fb此处填写您的FacebookAppId" />
            </intent-filter>
        </activity>
    </application>
</manifest>

配置说明：

• fb此处填写您的FacebookAppId: 替换为 fb + 您的 Facebook App ID，例如 fb123456789
• 此处填写您的ClientToken: 替换为您的 Facebook Client Token
• 此处填写您的FacebookAppId: 替换为您的 Facebook App ID（不带 fb 前缀）

快速开始

导入插件

uni-app x 版本

import * as metaSdk from "@/uni_modules/tt-meta-sdk";

export default {
    data() {
        return {
            metaSDK: null as metaSdk.TTMetaSDK | null,
        }
    },
    onLoad() {
        // 初始化Meta SDK实例
        this.metaSDK = metaSdk.getTTMetaSDK()
    },
    methods: {
        // 使用SDK功能
    }
}

uni-app 版本

import * as metaSdk from "@/uni_modules/tt-meta-sdk";

export default {
    data() {
        return {
            metaSDK: metaSdk.TTMetaSDK,
        }
    },
    onLoad() {
        // 初始化Meta SDK实例
        this.metaSDK = metaSdk.getTTMetaSDK()
    },
    methods: {
        // 使用SDK功能
    }
}

授权登录

参数说明

TTMetaLoginOptions

返回值 TTMetaLoginSuccess

行为说明

• 登录成功必然返回 code（访问令牌字符串/授权码）。
• 用户信息字段（userID/name/pictureURL/email）在权限允许且平台可获取时返回。
• 若获取用户信息失败：
  • iOS：仍返回成功，且仅包含 code，其余字段为 null。
  • Android：返回失败并携带错误码 106（用户信息获取失败）。建议前端以 code 为主，在后端通过 Graph API 拉取用户资料，避免依赖端侧。

示例代码

uni-app x 版本

// Facebook 授权登录
handleFacebookLogin() {
    this.metaSDK?.login({
        permissions: ["public_profile", "email"], // 请求权限
        success: (result) => {
            console.log("✅ Facebook 登录成功:", result);
            console.log("授权码:", result.code);

            // 可以将授权码发送到后端服务器进行进一步处理
            this.sendCodeToServer(result.code)
        },
        fail: (error) => {
            console.error("❌ Facebook 登录失败:", error);
            uni.showToast({
                title: '登录失败',
                icon: 'error'
            })
        },
        complete: (result) => {
            console.log("Facebook 登录完成");
        }
    } as metaSdk.TTMetaLoginOptions)
}

// 发送授权码到后端服务器
sendCodeToServer(code: string) {
    uni.request({
        url: 'https://your-server.com/api/facebook/login',
        method: 'POST',
        data: { code },
        success: (res) => {
            // 处理登录成功逻辑
            console.log('登录成功:', res.data)
        },
        fail: (err) => {
            console.error('登录请求失败:', err)
        }
    })
}

uni-app 版本

// Facebook 授权登录
handleFacebookLogin() {
    this.metaSDK.login({
        permissions: ["public_profile", "email"], // 请求权限
        success: (result) => {
            console.log("✅ Facebook 登录成功:", result);
            console.log("授权码:", result.code);

            // 可以将授权码发送到后端服务器进行进一步处理
            this.sendCodeToServer(result.code)
        },
        fail: (error) => {
            console.error("❌ Facebook 登录失败:", error);
            uni.showToast({
                title: '登录失败',
                icon: 'error'
            })
        },
        complete: (result) => {
            console.log("Facebook 登录完成");
        }
    })
}

// 发送授权码到后端服务器
sendCodeToServer(code) {
    uni.request({
        url: 'https://your-server.com/api/facebook/login',
        method: 'POST',
        data: { code },
        success: (res) => {
            // 处理登录成功逻辑
            console.log('登录成功:', res.data)
        },
        fail: (err) => {
            console.error('登录请求失败:', err)
        }
    })
}

退出登录

参数说明

TTMetaLogoutOptions

示例代码

uni-app x 版本

// Facebook 退出登录
handleFacebookLogout() {
    this.metaSDK?.logout({
        success: () => {
            console.log("✅ Facebook 退出登录成功");
            uni.showToast({
                title: '退出成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Facebook 退出登录失败:", error);
            uni.showToast({
                title: '退出失败',
                icon: 'error'
            })
        },
        complete: () => {
            console.log("Facebook 退出登录完成");
        }
    } as metaSdk.TTMetaLogoutOptions)
}

uni-app 版本

// Facebook 退出登录
handleFacebookLogout() {
    this.metaSDK.logout({
        success: () => {
            console.log("✅ Facebook 退出登录成功");
            uni.showToast({
                title: '退出成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Facebook 退出登录失败:", error);
            uni.showToast({
                title: '退出失败',
                icon: 'error'
            })
        },
        complete: () => {
            console.log("Facebook 退出登录完成");
        }
    })
}

Facebook 分享

本插件支持三种类型的分享：图片分享、链接分享、视频分享。

注意：所有分享功能默认使用 Facebook Feed（动态）分享对话框。

分享图片

参数说明

TTMetaShareImageOptions

返回值 TTMetaShareSuccess

示例代码

uni-app x 版本

// Facebook 分享图片
handleShareImage() {
    this.metaSDK?.shareImage({
        imagePath: "/static/logo.png", // 本地图片路径
        desc: "这是一张测试图片",
        hashtags: ["#Test", "#Facebook"],
        success: () => {
            console.log("✅ Facebook 分享图片成功");
            uni.showToast({
                title: '分享成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Facebook 分享图片失败:", error);
            if (error.cause != null) {
                console.error("原始错误:", error.cause.message);
            }
            uni.showToast({
                title: '分享失败: ' + error.errMsg,
                icon: 'error'
            })
        },
        complete: () => {
            console.log("Facebook 分享图片完成");
        }
    } as metaSdk.TTMetaShareImageOptions)
}

uni-app 版本

// Facebook 分享图片
handleShareImage() {
    this.metaSDK.shareImage({
        imagePath: "/static/logo.png", // 本地图片路径
        desc: "这是一张测试图片",
        hashtags: ["#Test", "#Facebook"],
        success: () => {
            console.log("✅ Facebook 分享图片成功");
            uni.showToast({
                title: '分享成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Facebook 分享图片失败:", error);
            if (error.cause != null) {
                console.error("原始错误:", error.cause.message);
            }
            uni.showToast({
                title: '分享失败: ' + error.errMsg,
                icon: 'error'
            })
        },
        complete: () => {
            console.log("Facebook 分享图片完成");
        }
    })
}

分享链接

参数说明

TTMetaShareLinkOptions

重要提示：

• title、description、imageUrl 会从链接的 HTML meta 标签自动获取
• 如果需要自定义这些信息，需要在链接的 HTML 中添加相应的 meta 标签：

  <meta property="og:title" content="页面标题" />
  <meta property="og:description" content="页面描述" />
  <meta property="og:image" content="图片URL" />

示例代码

uni-app x 版本

// Facebook 分享链接
handleShareLink() {
    this.metaSDK?.shareLink({
        linkUrl: "https://www.dcloud.io/",
        quote: "这是一个测试链接分享",
        hashtags: ["#DCloud", "#UniApp"],
        success: () => {
            console.log("✅ Facebook 分享链接成功");
            uni.showToast({
                title: '分享成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Facebook 分享链接失败:", error);
            if (error.cause != null) {
                console.error("原始错误:", error.cause.message);
            }
            uni.showToast({
                title: '分享失败: ' + error.errMsg,
                icon: 'error'
            })
        },
        complete: () => {
            console.log("Facebook 分享链接完成");
        }
    } as metaSdk.TTMetaShareLinkOptions)
}

uni-app 版本

// Facebook 分享链接
handleShareLink() {
    this.metaSDK.shareLink({
        linkUrl: "https://www.dcloud.io/",
        quote: "这是一个测试链接分享",
        hashtags: ["#DCloud", "#UniApp"],
        success: () => {
            console.log("✅ Facebook 分享链接成功");
            uni.showToast({
                title: '分享成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Facebook 分享链接失败:", error);
            if (error.cause != null) {
                console.error("原始错误:", error.cause.message);
            }
            uni.showToast({
                title: '分享失败: ' + error.errMsg,
                icon: 'error'
            })
        },
        complete: () => {
            console.log("Facebook 分享链接完成");
        }
    })
}

分享视频

参数说明

TTMetaShareVideoOptions

重要提示：

• ShareVideoContent 不支持直接设置 title 和 description
• 视频的标题和描述需要通过其他方式设置，或由 Facebook SDK 自动处理

示例代码

uni-app x 版本

// Facebook 分享视频
handleShareVideo() {
    this.metaSDK?.shareVideo({
        videoPath: "/static/test.mp4", // 本地视频路径
        previewImageUrl: "/static/logo.png", // 可选：视频预览图
        hashtags: ["#Video", "#Test"],
        success: () => {
            console.log("✅ Facebook 分享视频成功");
            uni.showToast({
                title: '分享成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Facebook 分享视频失败:", error);
            if (error.cause != null) {
                console.error("原始错误:", error.cause.message);
            }
            uni.showToast({
                title: '分享失败: ' + error.errMsg,
                icon: 'error'
            })
        },
        complete: () => {
            console.log("Facebook 分享视频完成");
        }
    } as metaSdk.TTMetaShareVideoOptions)
}

uni-app 版本

// Facebook 分享视频
handleShareVideo() {
    this.metaSDK.shareVideo({
        videoPath: "/static/test.mp4", // 本地视频路径
        previewImageUrl: "/static/logo.png", // 可选：视频预览图
        hashtags: ["#Video", "#Test"],
        success: () => {
            console.log("✅ Facebook 分享视频成功");
            uni.showToast({
                title: '分享成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Facebook 分享视频失败:", error);
            if (error.cause != null) {
                console.error("原始错误:", error.cause.message);
            }
            uni.showToast({
                title: '分享失败: ' + error.errMsg,
                icon: 'error'
            })
        },
        complete: () => {
            console.log("Facebook 分享视频完成");
        }
    })
}

错误处理

错误码说明

常见问题

Q: 为什么登录失败？

A: 请检查以下几点：

1. 确保已在 Facebook 开发者平台正确配置应用
2. 检查 App ID 是否正确配置
3. 确保应用包名和签名与 Facebook 开发者平台配置一致
4. 检查网络连接是否正常
5. 如出现 "Duplicate class" 或 AndroidX 相关编译错误，清理缓存并检查是否有第三方依赖与 Facebook AndroidX 版本冲突
6. 若未收到回调，确认 Activity Result 是否已由插件注册（无需额外原生代码），同时避免在宿主侧覆盖插件设置

Q: 如何获取更多用户信息？

A:

1. 在 permissions 参数中添加所需权限，如 ["public_profile", "email", "user_friends"]
2. 通过后端使用获取到的访问令牌调用 Facebook Graph API
   • 推荐做法：前端仅获取 code，用户信息在后端统一获取，减少端侧差异（iOS/Android 行为差异见上）

Q: 支持哪些权限？

A: 常用权限包括：

• public_profile: 基本公开信息
• email: 邮箱地址
• user_friends: 好友列表
• user_birthday: 生日信息
• user_location: 位置信息

更多权限请参考 Facebook 权限文档

Q: 如何处理权限被拒绝的情况？

A:

1. 在 fail 回调中检查错误信息
2. 向用户说明权限的必要性
3. 引导用户重新授权或使用替代方案

Q: 登录后如何保持登录状态？

A:

1. Facebook SDK 会自动管理登录状态
2. 应用重启后可以检查当前登录状态
3. 建议在后端验证访问令牌的有效性
   4. Android 端退出登录前会检查是否已登录，未登录会返回错误码 103

Q: 如何在开发环境中测试？

A:

1. 在 Facebook 开发者平台添加测试用户
2. 确保开发环境的包名和签名与配置一致
3. 使用测试用户账号进行登录测试

Q: 生产环境部署注意事项？

A:

1. 确保应用已通过 Facebook 审核
2. 使用生产环境的 App ID 和 App Secret
3. 配置正确的隐私政策和服务条款链接
4. 测试所有登录流程和权限请求

Q: 分享功能支持哪些格式？

A:

• 图片分享：支持本地图片路径，常见格式如 JPG、PNG 等
• 链接分享：支持 HTTP/HTTPS URL，会自动从链接的 meta 标签获取标题、描述和预览图
• 视频分享：支持本地视频路径，常见格式如 MP4 等

Q: 如何自定义链接分享的标题和描述？

A: 链接分享的标题、描述和预览图会从链接的 HTML meta 标签自动获取。需要在链接的 HTML 中添加 Open Graph 标签：

<meta property="og:title" content="页面标题" />
<meta property="og:description" content="页面描述" />
<meta property="og:image" content="https://example.com/image.jpg" />

Q: 分享时如何添加 hashtag？

A:

1. 在分享选项的 hashtags 参数中传入数组，例如：["#Test", "#Facebook"]
2. 注意：Facebook SDK 只支持单个 hashtag，会使用数组的第一个元素
3. 格式应为 "#标签名"，如果没有 # 前缀会自动添加
4. Hashtag 会显示在分享对话框中，用户可以在发布前移除

Q: 分享失败时如何查看详细错误信息？

A: 分享失败的回调中，error 对象包含：

• errCode: 错误码
• errMsg: 错误信息
• cause: 原始错误对象（如果存在），包含 code 和 message 属性

可以通过 error.cause.message 查看 Facebook SDK 返回的详细错误信息。

Q: 分享功能是否需要用户登录？

A: 不需要。分享功能可以独立使用，不需要用户先登录 Facebook。但如果需要分享到特定用户的动态或使用某些高级功能，可能需要相应的权限。

📞 技术支持: 如遇到问题，请通过 IM 联系技术支持 📚 更多资源: Facebook 开发者文档

🎉 祝您开发愉快！