{"id":25065465,"url":"https://github.com/open-yescoin/telegram-unity-bridge","last_synced_at":"2025-04-14T18:31:15.589Z","repository":{"id":267922338,"uuid":"902748525","full_name":"Open-Yescoin/Telegram-Unity-Bridge","owner":"Open-Yescoin","description":"Telegram Miniapp Bridge SDK for Unity is a powerful SDK developed by Yescoin designed to bridge the functionality of Telegram Miniapps with Unity, enabling seamless integration between your Unity-based applications and the Telegram Miniapp platform.","archived":false,"fork":false,"pushed_at":"2025-01-09T14:17:52.000Z","size":595,"stargazers_count":37,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-28T06:51:15.309Z","etag":null,"topics":["sdk","telegram-mini-app","ump","unity"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Open-Yescoin.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-13T07:31:46.000Z","updated_at":"2025-03-20T12:10:34.000Z","dependencies_parsed_at":"2024-12-13T09:26:26.393Z","dependency_job_id":"d7e5e655-f7a0-4323-9ecd-033756ed1b9c","html_url":"https://github.com/Open-Yescoin/Telegram-Unity-Bridge","commit_stats":null,"previous_names":["siykt/atp.tma.sdk","open-yescoin/telegram-unity-bridge"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Yescoin%2FTelegram-Unity-Bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Yescoin%2FTelegram-Unity-Bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Yescoin%2FTelegram-Unity-Bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Yescoin%2FTelegram-Unity-Bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Yescoin","download_url":"https://codeload.github.com/Open-Yescoin/Telegram-Unity-Bridge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248936608,"owners_count":21186061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["sdk","telegram-mini-app","ump","unity"],"created_at":"2025-02-06T19:22:46.603Z","updated_at":"2025-04-14T18:31:15.566Z","avatar_url":"https://github.com/Open-Yescoin.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Telegram-Unity-Bridge 集成指南\n\n\u003ca href=\"https://github.com/Open-Yescoin/Telegram-Unity-Bridge/blob/main/README.md\"\u003eDocuments\u003c/a\u003e\n·\n\u003ca href=\"https://github.com/Open-Yescoin/Telegram-Unity-Bridge/blob/main/README-zh.md\"\u003e中文 README\u003c/a\u003e\n\n\u003c/div\u003e\n\n本 README 将为您介绍 **Telegram-Unity-Bridge**，包括如何在 Unity 中设置并使用所提供的 C# 类与示例脚本，以便与 Telegram MiniApp 游戏 SDK 环境进行集成。\n\n## 概览\n\nTelegram-Unity-Bridge 旨在简化 Unity 应用与 Telegram MiniApp 游戏环境之间的通信。通过在 C# 中使用 `[DllImport(\"__Internal\")]` 来绑定定义在 jslib 文件中的各种 JavaScript 函数，这些函数可让 Unity 开发者：\n\n- 管理钱包连接与支付流程。\n- 获取启动参数、用户信息以及初始化数据。\n- 控制 MiniApp 的用户界面（如标题栏颜色、背景、底栏颜色等）。\n- 请求设备功能（例如：电话访问权限、写入权限、联系人信息）。\n- 与 Telegram 环境交互（分享动态、打开链接、请求震动、设置表情符号状态等）。\n\n## 先决条件\n\n- Unity 2020.3 及以上版本（建议使用 LTS 版本）。\n- 需要将目标平台设置为 WebGL，因为 SDK 利用 JavaScript 库和特定于浏览器的能力。\n- 将 JavaScript 库文件（`.jslib`）集成到 Unity 项目中。  \n  请确保您已包含：\n  - `index.jslib`（包含 JavaScript 方法）。\n  - 与其对应的 C# 脚本。\n\n## 文件夹结构\n\n典型项目结构示例：\n\n```\nRuntime/\n  YesTMABridge/\n    YesTMABridge.cs\n    index.jslib\nSamples/\n  Example/\n    YesTMABridgeActions.cs\n```\n\n## 快速开始\n\n1. **引入 JavaScript 库：**  \n   将 `index.jslib` 放置在 `Runtime/` 文件夹下。Unity 会在 WebGL 构建时自动关联该文件。\n\n2. **引入 C# 封装类：**\n\n   - `YesTMABridge.cs`：包含 `[DllImport]` 声明，用于在 C# 与 JavaScript 间建立桥梁。\n   - `YesTMABridgeActions.cs`（示例脚本）：展示如何调用 SDK 方法并订阅相关事件。\n\n3. **在场景中添加 TGMiniAppGameSDKProvider 组件：**\n\n   - 在 Unity 场景中创建一个空的 `GameObject`。\n   - 将 `YesTMABridge.cs` 附加到该 GameObject 上。\n   - 这样可确保提供者（provider）处理回调并维护事件订阅。\n\n4. **配置并使用示例脚本（YesTMABridgeActions）：**\n\n   - 将 `YesTMABridgeActions.cs` 附加到另一个 GameObject 上。\n   - 在 `YesTMABridgeActions.cs` 中，会通过 `FindObjectOfType\u003cTGMiniAppGameSDKProvider\u003e()` 在运行时获取 `TGMiniAppGameSDKProvider` 引用。\n   - 确保在 `YesTMABridgeActions` 初始化前，场景中已存在 `TGMiniAppGameSDKProvider`。\n\n5. **测试集成效果：**\n   - 当在兼容的环境（Telegram MiniApp 环境）中运行 WebGL 构建时，像 `connectWallet()` 或 `payWithTon()` 这类调用会触发相应的 JS 函数。\n   - 类似 `OnPhoneAccessReceived`、`OnWriteAccessReceived`、`OnContactReceived` 等事件会由 JS 环境触发并在 C# 中得到响应。\n\n## 关键组件\n\n### TGMiniAppGameSDKProvider\n\n- **作用：**  \n  C# 与 JavaScript 调用间的桥梁。通过 `[DllImport(\"__Internal\")]` 访问 `index.jslib` 中的 JS 方法。\n- **特性：**\n\n  - 钱包管理（连接、断开、获取状态、获取地址）。\n  - Ton 支付处理。\n  - 获取启动参数、用户信息、启动参数（start params）和原始初始化数据。\n  - 修改 MiniApp UI 元素（头部、背景、底栏颜色等）。\n  - 管理屏幕方向、确认对话框、视口等。\n  - 分享内容（故事、URL）、访问设备功能（震动、剪贴板、联系人、电话、写入权限）。\n  - 请求和设置表情状态。\n\n- **事件：**  \n  提供者定义了一些事件（例如 `OnContactReceived`、`OnPhoneAccessReceived`），由 JavaScript 回调触发。可在您的脚本中订阅这些事件，处理异步响应。\n\n### YesTMABridgeActions（示例脚本）\n\n- **作用：**\n  提供实际示例，展示如何：\n\n  - 订阅来自 SDK 提供者的事件。\n  - 调用 SDK 方法控制 MiniApp 环境。\n  - 处理事件响应，并将结果整合到您的游戏逻辑中。\n\n- **使用方法：**\n  - 将脚本挂载到某个 GameObject 上。\n  - 使用 UI 按钮触发诸如 `ConnectWallet()`、`PayWithTON()`、`CloseMiniApp()` 等方法的调用。\n  - 在 Unity 控制台观察交互和事件的调试日志。\n\n## 常见使用场景\n\n1. **钱包交互：**\n\n   - `ConnectWallet()` 启动钱包连接流程。\n   - `CheckWalletConnection()` 检查当前钱包连接状态。\n   - `GetWalletAddress()` 获取用户钱包地址。\n   - `PayWithTON()` 使用 Ton 进行支付。\n\n2. **UI 与屏幕方向控制：**\n\n   - `SetHeaderColor()`、`SetBackgroundColor()`、`SetBottomBarColor()` 根据游戏主题调整 MiniApp UI。\n   - `EnableVerticalOrientation()` 或 `DisableVerticalOrientation()` 控制屏幕布局方向。\n   - `ShowBackButton()` 或 `HideBackButton()` 控制返回按钮的显示与隐藏。\n\n3. **用户信息与启动参数：**\n\n   - `TGMiniAppGameSDKProvider.getUserInfo()` 获取用户数据，以便根据用户特征定制体验。\n   - `TGMiniAppGameSDKProvider.getLaunchParams()` 获取 Telegram 环境传入的初始参数。\n\n4. **设备功能与权限请求：**\n\n   - `RequestPhoneAccess()`、`RequestWriteAccess()`、`RequestContact()` 请求相应权限。\n   - 在 `OnContactReceived` 事件处理程序中使用获取的联系人信息为游戏内功能提供支持。\n\n5. **分享与链接：**\n   - `ShareStory()`、`ShareURL()` 以实现社交分享功能。\n   - `OpenLink()` 和 `OpenTelegramLink()` 在 MiniApp 中打开外部内容或 Telegram 链接。\n\n## 疑难解答\n\n- **Error CS0120：“需要对象引用...”：**  \n  确保您在访问事件时使用 `TGMiniAppGameSDKProvider` 的实例，而不是类名本身。  \n  例如：\n\n  ```csharp\n  TGMiniAppGameSDKProvider sdkInstance = FindObjectOfType\u003cTGMiniAppGameSDKProvider\u003e();\n  sdkInstance.OnTextFromClipboardReceived += MyEventHandler;\n  ```\n\n- **SDK 方法无响应：**\n\n  - 确认您的 WebGL 构建在正确的环境中运行（JavaScript 方法已正确集成）。\n  - 检查浏览器控制台日志是否有 JS 报错。\n  - 确保 `.jslib` 文件位于 `Runtime/` 下。\n\n- **事件未触发：**\n  - 确保包含 `TGMiniAppGameSDKProvider` 的 Unity 对象在运行时处于激活状态。\n  - 检查 `.jslib` 文件中的 JS 回调是否正确实现。\n\n## 最佳实践\n\n- **错误处理：**  \n  在事件处理程序中实现健壮的错误处理和用户反馈。\n\n- **安全与隐私：**  \n  使用用户数据（如联系人、用户信息）时，确保遵守隐私法规并获得用户同意。\n\n- **性能考虑：**  \n  使用 `JSON.stringify` 与 `JsonUtility.FromJson` 对于大型对象可能较慢。可考虑缓存结果或减少大型数据传输。\n\n## 结论\n\n通过 Telegram-Unity-Bridge，您可以轻松实现 Unity 与 Telegram MiniApp 游戏环境之间的集成。按上述步骤操作，并基于示例脚本进行定制，您即可轻松实现钱包连接、获取用户数据、操控 UI、分享动态、调用设备功能，从而为用户带来更丰富的应用内体验。\n\n## API 参考\n\n### 方法\n\n#### 钱包与支付\n\n- **connectWallet()**  \n  启动钱包连接过程。\n\n- **disconnectWallet()**  \n  断开当前已连接的钱包。\n\n- **getWalletConnected() : bool**  \n  若当前已连接钱包返回 `true`，否则为 `false`。\n\n- **getWalletAddress() : string**  \n  返回当前已连接钱包的地址。\n\n- **payWithTon(int amount, string comment)**  \n  启动使用 Ton 加密货币的支付流程。\n  - **参数：**\n    - `amount`：支付 Ton 的数量。\n    - `comment`：可选备注信息。\n\n#### 应用参数与用户信息\n\n- **getLaunchParams() : string**  \n  以 JSON 字符串形式返回 Telegram 环境传递的启动参数。\n\n- **getUserInfo() : string**  \n  以 JSON 字符串形式返回用户信息。可使用 `TGMiniAppGameSDKProvider.GetUserInfo()` 将其转换为 `TMAUser` 对象。\n\n- **getStartParam() : string**  \n  返回启动应用时传入的特定 `startParam` 字符串。\n\n- **getInitDataRaw() : string**  \n  返回原始的初始化数据字符串。\n\n#### MiniApp UI 控制\n\n- **miniAppSetHeaderColor(string color)**  \n  设置 MiniApp 顶部标题栏颜色。\n\n  - **示例:** `\"#FF5733\"`\n\n- **miniAppSetBgColor(string color)**  \n  设置 MiniApp 背景颜色。\n\n- **miniAppSetBottomBarColor(string color)**  \n  设置 MiniApp 底栏颜色。\n\n- **miniAppClose()**  \n  关闭 MiniApp 。\n\n- **miniAppIsActive**  \n  获取 MiniApp 当前状态。\n\n- **viewportExpand()**  \n  扩展 MiniApp 的视口。\n\n- **viewportRequestFullscreen()**  \n  请求 MiniApp 全屏显示。\n\n- **backButtonShow()**  \n  显示 MiniApp 中的返回按钮。\n\n- **backButtonHide()**  \n  隐藏 MiniApp 中的返回按钮。\n\n- **enableConfirmation()**  \n  启用在某些操作前的确认对话框。\n\n- **disableConfirmation()**  \n  禁用确认对话框。\n\n- **enableVertical()**  \n  启用竖屏方向强制。\n\n- **disableVertical()**  \n  禁用竖屏方向强制。\n\n#### 分享与链接\n\n- **shareStory(string mediaUrl, string text, string widgetLinkUrl, string widgetLinkName)**  \n  分享包含媒体内容、文字及可选小部件链接的动态。\n\n- **openTelegramLink(string link)**  \n  在 MiniApp 环境中打开指定的 Telegram 链接。\n\n- **openLink(string link, bool tryBrowser, bool tryInstantView)**  \n  打开指定链接，可选尝试在浏览器或 Instant View 中打开。\n\n- **shareURL(string url, string text)**  \n  分享指定 URL 及相应文本。\n\n#### 设备功能与权限\n\n- **requestVibration(int style)**  \n  请求设备震动（若设备支持）。`style` 参数可能用于定义震动模式。\n\n- **addToHomeScreen**  \n  将 MiniApp 添加到用户的主屏幕。\n\n- **requestCheckHomeScreenStatus**  \n  请求检查主屏幕状态。\n\n- **requestPhoneAccess()**  \n  请求访问用户电话功能（如适用）。\n\n- **requestWriteAccess()**  \n  请求写入权限。\n\n- **requestContact()**  \n  请求用户的联系人信息。\n\n- **requestEmojiStatusAccess()**  \n  请求访问或管理用户的表情状态。\n\n- **requestSetEmojiStatus(string customEmojiId, int duration)**  \n  请求在指定时长内设置用户的表情状态。\n\n  - **参数：**\n    - `customEmojiId`：要设置的表情符号 ID。\n    - `duration`：表情状态应保持活跃的时间（秒）。\n\n- **requestReadTextFromClipboard()**  \n  请求从系统剪贴板读取文本内容。\n\n#### 工具函数\n\n- **safeStringify(object obj, int space) : string**  \n  安全地将对象序列化为 JSON 字符串，处理循环引用问题。\n\n- **str2Buffer(string str) : string**  \n  将 C# 字符串转换为供 JS/Unity 交互使用的内存缓冲（UTF-8）。\n\n- **objGet(object obj, string path, object defaultValue) : string**  \n  按路径检索嵌套对象属性。如未找到则返回 `defaultValue`。\n\n### 事件\n\n**所有事件均基于实例。** 您需要引用 `TGMiniAppGameSDKProvider` 的实例来订阅或取消订阅事件。\n\n- **OnPhoneAccessReceived**：  \n  当电话访问请求完成时触发。  \n  **签名：** `event Action\u003cstring\u003e OnPhoneAccessReceived`\n\n- **OnWriteAccessReceived**：  \n  当写入权限请求完成时触发。  \n  **签名：** `event Action\u003cstring\u003e OnWriteAccessReceived`\n\n- **OnContactReceived**：  \n  当收到联系人信息时触发。  \n  **签名：** `event Action\u003cTMARequestedContact\u003e OnContactReceived`  \n  **说明：** `TMARequestedContact` 包含 `userId`、`phoneNumber`、`firstName`、`lastName` 等详细信息。\n\n- **OnEmojiStatusAccessReceived**：  \n  当表情状态访问请求完成时触发。  \n  **签名：** `event Action\u003cstring\u003e OnEmojiStatusAccessReceived`\n\n- **OnTextFromClipboardReceived**：  \n  当成功从剪贴板获取文本时触发。  \n  **签名：** `event Action\u003cstring\u003e OnTextFromClipboardReceived`\n\n### 示例用法\n\n```csharp\npublic class MyExample : MonoBehaviour\n{\n    private TGMiniAppGameSDKProvider sdkProvider;\n\n    void Start()\n    {\n        sdkProvider = FindObjectOfType\u003cTGMiniAppGameSDKProvider\u003e();\n        if (sdkProvider != null)\n        {\n            sdkProvider.OnContactReceived += HandleContact;\n        }\n\n        // 连接钱包\n        TGMiniAppGameSDKProvider.connectWallet();\n\n        // 获取用户信息\n        TMAUser user = TGMiniAppGameSDKProvider.GetUserInfo();\n        Debug.Log(\"用户的名字: \" + user.firstName);\n    }\n\n    void OnDestroy()\n    {\n        if (sdkProvider != null)\n        {\n            sdkProvider.OnContactReceived -= HandleContact;\n        }\n    }\n\n    private void HandleContact(TMARequestedContact contactInfo)\n    {\n        Debug.Log(\"获取到联系人信息: \" + contactInfo.contact.firstName + \" \" + contactInfo.contact.lastName);\n    }\n}\n```\n\n### 备注\n\n- 在 Unity 中调用这些方法时，请确保在 WebGL 构建中运行，并且已正确设置 Telegram MiniApp 环境。\n- 确保 `TGMiniAppGameSDKProvider` 存在且在场景中处于激活状态，以处理事件和回调。\n- 非静态事件需要 `TGMiniAppGameSDKProvider` 的实例进行订阅。不要直接使用类名订阅事件。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-yescoin%2Ftelegram-unity-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-yescoin%2Ftelegram-unity-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-yescoin%2Ftelegram-unity-bridge/lists"}