在Cocos Creator中使用Ton

1. 创建Telegram Mini App

1.1 如何创建一个Telegram Bot

  1. 在Telegram中搜索 @BotFather,这是一个官方的Bot管理员账号。

  2. 给@BotFather发送 /newbot 命令来创建一个新的Bot。

  3. 输入你的Bot名字,名字必须以"bot"结尾,比如 "MyAwesomeBot"。

  4. 输入Bot的用户名,必须是唯一的且以"bot"结尾,比如"my_awesome_bot"。

  5. 如果名字可用,@BotFather会返回你新创建Bot的访问Token,格式如: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11。请妥善保管此Token,不要泄露给他人。

1.2 设置Mini App的相关参数

  1. 给@BotFather发送 /mybots 命令,选择你刚创建的Bot。

  2. 点击 "Bot Settings" - "Menu Button" 设置Bot的菜单按钮。可以设置一些快捷操作按钮。

  3. 给@BotFather发送 /newapp 命令,选择你刚创建的Bot,进行以下设置:

    • 设置Mini App的Name,会在Telegram中展示。

    • 设置Mini App的Description,简要描述Mini App的功能。

    • 设置Mini App的Photo,尺寸为640x360 pixels。

    • 设置Mini App的URL(需要https)。这是Mini App的实际访问地址。

    设置成功后你将获得一个直接访问的链接,用户通过此链接可以直接打开Mini App。你也可以在聊天界面的附件菜单中找到刚创建的Mini App。

2. 导入cocos-telegram-miniapps拓展

  1. 在Cocos Creator中创建一个新的项目,选择Creator 3.8.3以上的版本

  2. 在项目中安装cocos-telegram-miniapps拓展

    点击菜单-打开扩展管理

3.在Cocos中初始化cocos-telegram-miniapps拓展 此方法会自动加载telegram-web-app.js到页面中, 方便操作window.Telegram.WebApp对象

    import { _decorator, Component, Node } from 'cc';
    import { TelegramWebApp } from './cocos-telegram-miniapps/scripts/telegram-web';
    const { ccclass, property } = _decorator;

    @ccclass('game')
    export class game extends Component {
        protected onLoad() {
            TelegramWebApp.Instance.init().then(res => {
                console.log("telegram web app init : ", res.success);
            });
        }
        start() {

        }


        update(deltaTime: number) {

        }
    }

3. 使用TonConnectUI连接钱包

  1. 安装@ton/cocos-sdk库 为了使用TonConnectUI, 需要安装@ton/cocos-sdk库,此库已经打包好了TonConnectUI,可以直接在cocos 游戏引擎中使用

npm install --save @ton/cocos-sdk@beta

  1. 初始化TonConnectUI对象

async initTonConnect() {
        this.connectUI = new TonConnectUI({
            manifestUrl: 'https://ton-connect.github.io/demo-dapp-with-wallet/tonconnect-manifest.json'
        });
      

        // 监听连接状态变化
        this.connectUI.onModalStateChange(state => {
            console.log("model state changed! : ", state);
            this.updateConnect();
        });

        // 监听钱包状态变化
        this.connectUI.onStatusChange(info => {
            console.log("wallet info status changed : ", info);
            this.updateConnect();
        });
        this.updateConnect();
}

  1. 连接钱包

    onConnect() {
        if (this.isConnected()) {
            this.connectUI.disconnect();
        } else {
            this.connectUI.openModal();
        }
    }

    public isConnected(): boolean {
        if (!this.connectUI) {
            console.error("ton ui not inited!");
            return false;
        }
        return this.connectUI.connected;
    }

    // 连接成功钱包后获取钱包地址
    private updateConnect() {
        if (this.isConnected()) {
            const address = this.connectUI.account.address;
            this.connectLabel.string = Address.parseRaw(address).toString({ testOnly: true, bounceable: false }).substring(0, 6) + '...';
        } else {
            this.connectLabel.string = "Connect";
        }
    }

4. 通过TonConnectUI发送Ton交易

  1. 初始化GameFi对象 为了方便操作Ton链上的Jetton合约sdk中封装好了方法,需要初始化一下

 async initTonConnect() {
        this.connectUI = new TonConnectUI({
            manifestUrl: 'https://ton-connect.github.io/demo-dapp-with-wallet/tonconnect-manifest.json'
        });
        this.cocosGameFi = await GameFi.create({
            connector: this.connectUI
        });
    }

  1. 调用cocosGameFi对象中的方法,既可操作Ton链相关的交易 例如获取JettonWallet的Data

const jettonData = await this.cocosGameFi.openJettonWallet(Address.parse("")).getData()
console.log(jettonData.balance)

更多方法可以查看 https://github.com/ton-org/game-engines-sdk

5. Telegram Mini APP 相关操作

5.1 Telegram Mini APP 文档介绍

  • 文档地址：https://core.telegram.org/bots/webapps

5.2 获取当前Telegram用户信息

  1. 导入cocos-telegram-miniapps 扩展后, 会在assets/cocos-telegram-miniapps/scripts/telegram-web.ts 中生成TelegramWebApp类,使用该对象既可调用TelegramMiniAPP的相关能力

  2. 如果页面在Telegram中打开，会自动初始化window.Telegram.WebApp对象

  3. 通过该对象的initData可以获取到一个类型为string的json值，包含当前用户信息

  4. 后端接口需要验证这个值以确保安全

  5. 验证通过后可获取当前用户信息并进行登录操作

验证逻辑参考文档：https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app

例如typescript版本的校验如下:

import { createHmac } from 'crypto';

function hmac(data: string, key: string | Buffer): Buffer {
    return createHmac('sha256', key).update(data).digest();
}

export function processTelegramData(qs: string, token: string): { ok: false } | { ok: true, data: Record<string, string> } {
    const sk = hmac(token, 'WebAppData')
    const parts = qs.split('&').map(p => p.split('='))
    const hashpart = parts.splice(parts.findIndex(p => p[0] === 'hash'), 1)[0]
    const dcs = parts.sort((a, b) => a[0] > b[0] ? 1 : -1).map(p => decodeURIComponent(p.join('='))).join('\n')
    if (hmac(dcs, sk).toString('hex') !== hashpart[1]) return { ok: false }
    const o: Record<string, string> = {}
    for (const part of parts) {
        o[part[0]] = decodeURIComponent(part[1])
    }
    return { ok: true, data: o }
}

  1. 在cocos环境中参考如下方式使用

// 获取用户认证信息
const userInitData = TelegramWebApp.Instance.getTelegramInitData();
// 前端通过登入接口, 将userInitData提交给后端,后端验证userInitData是否合法,可以做登录认证逻辑

5.3 调用分享

  1. 调用TelegramWebApp.Instance.share(url,text)方法打开该链接实现分享功能 注意：text字段会自动UrlEncode

5.4 调用支付

在Telegram Mini APP中, 除了可以使用Ton链的代币作为支付手段,也可以使用官方的Telegram Stars作为支付渠道

Telegram Stars 文档地址: https://core.telegram.org/bots/payments-stars

简单的介绍下Stars 支付流程,首先后端需要创建一个invoiceLink, 然后返回给前端, 前端调用TelegramWebApp.Instance.openInvoice(invoiceLink)方法打开支付页面, 当用户点击支付的时候,Telegram bot会发送 pre_checkout_query消息通知后端,后端需要处理是否允许支付，允许后支付成功Telegram bot 会发送successful_payment消息后端收到后处理支付订单业务流程既可.

详细的业务代码可以参考demo 工程 https://github.com/CocosTechLabs/flappy-bird

5.5 直接获取TelegramWebApp对象

TelegramWebApp.Instance.getTelegramWebApp()

此方法可以直接返回TelegramWebApp对象, 方便使用其他能力。 具体方法可以参考官方文档 https://core.telegram.org/bots/webapps#initializing-mini-apps

6. 发布

在编译时候, 需要修改编译选项设置,调整Target Environments > 0.5% 否则可能会遇到打包后无法加载的问题

7. 社区交流

Telegram: https://t.me/CocosStudioCommunity

下一页在Cocos Creator中使用EVM

最后更新于