Telegram Integration
It covers setting up a Passport client in Hub, setting up Passport login and submitting pre-approved transactions.
Overview
Telegram is a great tool for community building in the Web3 space. With Passport integration for Telegram Mini Apps, you can now drive conversion of your Telegram community into Passport registered users ready to play your game.
Immutable's Telegram integration supports authentication and pre-approved transaction signing which can enable actions like minting, crafting and transfers.
If you already have a Telegram Mini App or want to build one for your game, you can easily integrate Immutable Passport by following the implementation instructions below. Doing this will enable your users to mint NFTs, craft and make transfers inside the Telegram Mini App, allowing your game’s Web3 ecosystem to expand to Telegram.
To integrate Passport into your Telegram Mini App, you need to do the following:
- Set up Immutable Hub
- Initialise Passport
- Set up Passport Login
- Submit Transactions
Below are partial code snippets that demonstrate the essential parts of each of these steps. If you want to see the full implementation, you can take a look at our Telegram Mini App Example.
For more details on each step, refer to the Immutable Passport specification.
Recommended approach
To date, the user experience in popular Telegram games has been biased towards the ability to allow users to play instantly. Therefore, you should maintain this user experience in your implementation.
This means that you will allow players to play the game without connecting to Passport.
Once they win or achieve rewards, and you decide to reward the player with an on-chain asset, we then recommend signing into Passport to claim the asset minted on Immutable zkEVM.
We also recommend this asset has utility within your Immutable zkEVM game downstream. We believe this implementation will give you the most successful user acquisition benefit.
Implementation
Due to variations in how pop-ups are handled across devices in the Telegram Mini App browser, only pre-approved transactions are supported.
See the pre-approved transactions page for more information on setting up pre-approved transactions.
1. Immutable Hub setup
Create a Passport client in the Immutable Hub. For Telegram Mini App support ensure that the Application Type is Native.
2. Passport initialisation
When initialising the Passport instance, ensure that crossSdkBridgeEnabled: true is provided to enable pre-approved transactions.
export const passportInstance = new passport.Passport({
baseConfig: new ImmutableConfiguration({ environment: Environment.SANDBOX }),
// The client ID of the application created in Hub
clientId: process.env.NEXT_PUBLIC_CLIENT_ID || "",
// The redirect URI set in the application created in Hub
redirectUri: process.env.NEXT_PUBLIC_REDIRECT_URI || "",
// The logout redirect URI set in the application created in Hub
logoutRedirectUri: process.env.NEXT_PUBLIC_LOGOUT_REDIRECT_URI || "",
audience: "platform_api",
scope: "openid offline_access email transact",
// Set crossSdkBridgeEnabled to enable pre-approved transactions
crossSdkBridgeEnabled: true,
});
3. Passport login
For logging in successfully across any device in the Telegram Mini App browser use the loginWithDeviceFlow() method instead of the login() method. Ensure the Passport client you setup earlier in the Immutable Hub is configured as a Native Application Type.
// Use loginWithDeviceFlow as the login method for Telegram Mini App to ensure support for all devices
const deviceFlowParams = await passportInstance.loginWithDeviceFlow();
// Open the device flow url using the openLink function on the telegram sdk
WebApp.openLink(deviceFlowParams.url);
// Wait for the user to complete the login before calling eth_requestAccounts
await passportInstance.loginWithDeviceFlowCallback(
deviceFlowParams.deviceCode,
deviceFlowParams.interval,
);
// Get the provider and call eth_requestAccounts to get the user's wallet address
const provider = passportInstance.connectEvm();
const [userAddress] = await provider.request({
method: "eth_requestAccounts",
});
setWalletAddress(userAddress);
4. Submitting transactions
Transactions in Telegram Mini Apps require pre-approvals to work across all devices. Once your contract function has been configured for pre-approval then the function can be called as usual. This will submit the transaction without displaying a confirmation popup to the user.
The below example is how to submit an asset transfer transaction. In this example the safeTransferFrom function needs to be configured for pre-approval for the collection you are calling the transfer function on.
// Setup the contract ABI with the safeTransferFrom function for transferring assets
const abi = [
"function safeTransferFrom(address from, address to, uint256 token_id)",
];
// Get the signer from the provider that was initialised in the Connect flow and create a contract instance
const signer = zkEvmProvider.getSigner();
const contract = new ethers.Contract(collectionAddress, abi, signer);
try {
// Call the transfer function on the contract
await contract.safeTransferFrom(walletAddress, toAddress, tokenId);
setTransferSuccess(true);
} catch (error: any) {
setErrorMessage(error.message);
}
Full sample code
See the below demo on GitHub for an example of how to use Passport with a Telegram Mini App.
"use client";
import React from "react";
import Home from "./components/Home";
import { passport } from "@imtbl/sdk";
import { Environment, ImmutableConfiguration } from "@imtbl/sdk/config";
// #doc passport-telegram-mini-app-configuration
export const passportInstance = new passport.Passport({
baseConfig: new ImmutableConfiguration({ environment: Environment.SANDBOX }),
// The client ID of the application created in Hub
clientId: process.env.NEXT_PUBLIC_CLIENT_ID || "",
// The redirect URI set in the application created in Hub
redirectUri: process.env.NEXT_PUBLIC_REDIRECT_URI || "",
// The logout redirect URI set in the application created in Hub
logoutRedirectUri: process.env.NEXT_PUBLIC_LOGOUT_REDIRECT_URI || "",
audience: "platform_api",
scope: "openid offline_access email transact",
// Set crossSdkBridgeEnabled to enable pre-approved transactions
crossSdkBridgeEnabled: true,
});
// #enddoc passport-telegram-mini-app-configuration
export default function App() {
return <Home />;
}