This README provides an overview of the Telegram-Unity-Bridge, including how to set up and use the provided C# classes and sample scripts to integrate with a Telegram MiniApp Game SDK environment.

The Telegram-Unity-Bridge is designed to facilitate communication between a Unity application and the Telegram MiniApp Game environment. It provides C# bindings (via [DllImport("__Internal")]) for various JavaScript functions defined in jslib files. These functions enable Unity developers to:

• Manage wallet connections and payments.
• Retrieve launch parameters, user information, and initialization data.
• Control the mini-app UI (header color, background, bottom bar color, etc.).
• Request device capabilities (e.g., phone access, write access, contact information).
• Interact with the Telegram environment (share stories, open links, request vibration, set emoji status, etc.).

• Unity 2020.3 or newer (LTS recommended). Unity 6.1 is fully supported.
• A WebGL build target, as the SDK uses JavaScript libraries and browser-specific capabilities.
• WebGL Template Support: We provide a React-based WebGL template for optimized interface adaptation in the Telegram MiniApp environment. You can find the related resources in the apps/WebGLTemplate directory.
• The JavaScript library file (.jslib) integrated into the Unity project.
  Make sure you have:
  • index.jslib (containing JavaScript methods).
  • Corresponding C# scripts in your Unity project.

A typical project structure might look like this:

Runtime/
  YesTMABridge/
    YesTMABridge.cs
    index.jslib
Samples/
  Example/
    YesTMABridgeActions.cs

1. In the Unity Editor menu bar, select Window > Package Manager.
2. Click the + button in the top left corner and select Add package from git URL.
3. Enter the following Git URL:

   https://github.com/Open-Yescoin/Telegram-Unity-Bridge.git?path=/packages/YesTMABridge
   

4. Click Add and wait for the package manager to complete the installation.

1. Include the JavaScript Library:
   Place the index.jslib in Runtime/. Unity will automatically link this code into WebGL builds.

2. Include the C# Wrapper Classes:

   • YesTMABridge.cs: Contains [DllImport] declarations to bridge between C# and JavaScript.
   • YesTMABridgeActions.cs (Sample Script): Demonstrates how to call SDK methods and subscribe to events.

1. Configure WebGL Template (Important):

   • Copy the provided WebGLTemplate folder to your project's Assets/WebGLTemplates directory.
   • Open File > Build Settings, select the WebGL platform, and click Player Settings.
   • Under Player Settings > Resolution and Presentation, select the "Telegram-Unity-Bridge" template.

2. Add the TGMiniAppGameSDKProvider Component to the Scene:

   • Create an empty GameObject in your Unity scene.
   • Add Component → Search for TGMiniAppGameSDKProvider and add it to the GameObject.
   • Note: TGMiniAppGameSDKProvider is a MonoBehaviour class defined in YesTMABridge.cs. You can attach it directly from the Unity Inspector.
   • This ensures the provider can handle callbacks and maintain event subscriptions.

3. Configure and Use the Sample Script (YesTMABridgeActions):

   • Add YesTMABridgeActions.cs to another GameObject.
   • In YesTMABridgeActions.cs, a reference to TGMiniAppGameSDKProvider is obtained at runtime with FindObjectOfType<TGMiniAppGameSDKProvider>().
   • Make sure TGMiniAppGameSDKProvider is present in the scene before YesTMABridgeActions is initialized.

4. Testing the Integration:

   • When running the WebGL build in a compatible environment (Telegram MiniApp environment), calls to methods like connectWallet() or payWithTon() will invoke the corresponding JS functions.
   • Events such as OnPhoneAccessReceived, OnWriteAccessReceived, OnContactReceived, etc., will be triggered by the JS environment.

• Purpose: Bridges C# and JavaScript calls. It uses [DllImport("__Internal")] to access JavaScript methods in index.jslib.

• Features:

  • Wallet management (connect, disconnect, get status, get address).
  • Payments with Ton.
  • Retrieve launch parameters, user info, start params, and raw initialization data.
  • Modify mini-app UI elements.
  • Manage orientation, confirmation dialogs, and viewport settings.
  • Share content (stories, URLs).
  • Access device features (vibration, clipboard, contacts, phone, write access).
  • Request and set emoji status.

• Events:
  The provider defines events (e.g., OnContactReceived, OnPhoneAccessReceived) that are triggered by JavaScript callbacks. Subscribe to these events in your scripts to handle asynchronous responses.

• Purpose: Serves as a practical example of how to:

  • Subscribe to events from the SDK provider.
  • Call SDK methods to control the mini-app environment.
  • Handle responses from events and integrate them into your game logic.

• Usage:

  • Attach it to a GameObject.
  • Set up UI buttons to call methods such as ConnectWallet(), PayWithTON(), CloseMiniApp(), etc.
  • Observe Unity's Console to see debug logs of the interactions and events.

1. Wallet Interaction:

   • ConnectWallet() to initiate a connection.
   • CheckWalletConnection() to verify connection status.
   • GetWalletAddress() to retrieve the user's wallet address.
   • PayWithTON() to process a Ton payment. Note: Make sure to provide a valid recipient wallet address.

2. UI and Orientation Control:

   • SetHeaderColor(), SetBackgroundColor(), and SetBottomBarColor() to adapt the mini-app's UI to your game's theme.
   • EnableVerticalOrientation() or DisableVerticalOrientation() to control layout.
   • ShowBackButton() or HideBackButton() to control navigation elements.

3. User Information and Launch Params:

   • TGMiniAppGameSDKProvider.getUserInfo() to retrieve user data and adapt the user experience accordingly.
   • TGMiniAppGameSDKProvider.getLaunchParams() to access initial parameters passed by the Telegram environment.

4. Device Capabilities and Permissions:

   • RequestPhoneAccess(), RequestWriteAccess(), RequestContact() to prompt permissions.
   • OnContactReceived event handler: Use this to populate in-game features with the user's contacts.

5. Sharing and Links:

   • ShareStory(), ShareURL() to integrate social features.
   • OpenLink() and OpenTelegramLink() to direct the user to external content or Telegram links.

• Error CS0120: "An object reference is required..."

  • Ensure that you're accessing instance events from a proper instance of TGMiniAppGameSDKProvider rather than the class name.
  • For example:

    TGMiniAppGameSDKProvider sdkInstance = FindObjectOfType<TGMiniAppGameSDKProvider>();
    sdkInstance.OnTextFromClipboardReceived += MyEventHandler;

• No Response from SDK Methods:

  • Confirm that your WebGL build is running in an environment where the JavaScript methods are properly integrated.
  • Check browser console logs for JavaScript errors.
  • Ensure that the .jslib file is located in Runtime/.

• Events Not Triggering:

  • Make sure your Unity object with TGMiniAppGameSDKProvider is active and present from the start.
  • Confirm that the JavaScript callbacks are correctly implemented in the .jslib file.

• Error Handling:
  Implement robust error handling and user feedback within event handlers.

• Security and Privacy:
  When handling user data (e.g., contacts, user info), ensure you comply with privacy regulations and user consent.

• Performance Considerations:
  Using JSON.stringify in JavaScript and JsonUtility.FromJson in C# can be relatively slow for large objects. Consider caching results or minimizing large data transfers.

The Telegram-Unity-Bridge simplifies integration between Unity and the Telegram MiniApp Game environment. By following the steps outlined above and customizing the example scripts, you can easily control wallet connections, retrieve user data, manipulate UI elements, share stories, and handle various device capabilities to enrich your users' in-app experience.

• connectWallet()
  Initiates a wallet connection process.
• disconnectWallet()
  Disconnects the currently connected wallet.
• getWalletConnected() : bool
  Returns true if a wallet is currently connected, otherwise false.
• getWalletAddress() : string
  Returns the currently connected wallet address as a string.
• payWithTon(string address, float amount, string comment)
  Initiates a payment using Ton cryptocurrency.
  • Parameters:
    • address: The recipient TON wallet address.
    • amount: The amount of Ton to pay.
    • comment: An optional message or note.

• getLaunchParams() : string
  Returns the launch parameters passed by the Telegram environment as a JSON string.
• getUserInfo() : string
  Returns the user information as a JSON string. Use TGMiniAppGameSDKProvider.GetUserInfo() to convert it to a TMAUser object.
• getStartParam() : string
  Returns a specific startParam string provided during the app launch.
• getInitDataRaw() : string
  Returns raw initialization data as a string.

• miniAppSetHeaderColor(string color)
  Sets the top header bar color of the mini-app.
  • Example: "#FF5733"
• miniAppSetBgColor(string color)
  Sets the background color of the mini-app.
• miniAppSetBottomBarColor(string color)
  Sets the bottom bar color of the mini-app.
• miniAppClose()
  Closes the mini-app.
• miniAppIsActive Gets the current mini-app status.
• viewportExpand()
  Expands the viewport within the mini-app.
• viewportRequestFullscreen()
  Requests fullscreen mode for the mini-app.
• backButtonShow()
  Shows a back button in the mini-app interface.
• backButtonHide()
  Hides the back button in the mini-app interface.
• enableConfirmation()
  Enables confirmation dialogs before certain actions.
• disableConfirmation()
  Disables confirmation dialogs.
• enableVertical()
  Enforces vertical orientation within the mini-app.
• disableVertical()
  Disables vertical orientation within the mini-app.

• shareStory(string mediaUrl, string text, string widgetLinkUrl, string widgetLinkName)
  Shares a story that can include media content, text, and an optional widget link.
• openTelegramLink(string link)
  Opens a specified Telegram link inside the mini-app environment.
• openLink(string link, bool tryBrowser, bool tryInstantView)
  Opens a given link, with optional attempts to open it in a browser or use Instant View.
• shareURL(string url, string text)
  Shares a URL along with accompanying text.

• requestVibration(int style)
  Requests a vibration action on the device (if supported). The style parameter may define the vibration pattern.
• addToHomeScreen Adds the mini-app to the user's home screen.
• requestCheckHomeScreenStatus Requests a check of the home screen status.
• requestPhoneAccess()
  Requests the user's phone capabilities (if applicable).
• requestWriteAccess()
  Requests write access permissions.
• requestContact()
  Requests user contact information.
• requestEmojiStatusAccess()
  Requests access to manage or view the user's emoji status.
• requestSetEmojiStatus(string customEmojiId, int duration)
  Requests to set the user's emoji status for a specified duration.
  • Parameters:
    • customEmojiId: Identifier for the emoji to set.
    • duration: How long the emoji status should remain active, in seconds.
• requestReadTextFromClipboard()
  Requests reading text content from the system clipboard.

• safeStringify(object obj, int space) : string
  Safely serializes an object to a JSON string, handling circular references.
• str2Buffer(string str) : string
  Converts a C# string into a memory buffer (UTF-8) for JS/Unity interop.
• objGet(object obj, string path, object defaultValue) : string
  Retrieves a nested object property by a path. Returns defaultValue if not found.

All events are instance-based. You must reference a TGMiniAppGameSDKProvider instance to subscribe or unsubscribe from these events.

• OnPhoneAccessReceived:
  Invoked when the phone access request completes.
  Signature: event Action<string> OnPhoneAccessReceived
• OnWriteAccessReceived:
  Invoked when the write access request completes.
  Signature: event Action<string> OnWriteAccessReceived
• OnContactReceived:
  Invoked when contact information is received.
  Signature: event Action<TMARequestedContact> OnContactReceived
  Note: TMARequestedContact includes details like userId, phoneNumber, firstName, and lastName.
• OnEmojiStatusAccessReceived:
  Invoked when the emoji status access request completes.
  Signature: event Action<string> OnEmojiStatusAccessReceived
• OnTextFromClipboardReceived:
  Invoked when text from the clipboard is successfully retrieved.
  Signature: event Action<string> OnTextFromClipboardReceived

public class MyExample : MonoBehaviour
{
    private TGMiniAppGameSDKProvider sdkProvider;

    void Start()
    {
        sdkProvider = FindObjectOfType<TGMiniAppGameSDKProvider>();
        if (sdkProvider != null)
        {
            sdkProvider.OnContactReceived += HandleContact;
        }

        // Connect wallet
        TGMiniAppGameSDKProvider.connectWallet();

        // Get user info
        TMAUser user = TGMiniAppGameSDKProvider.GetUserInfo();
        Debug.Log("User first name: " + user.firstName);

        // Pay with TON (example)
        string recipientAddress = "YOUR_TON_WALLET_ADDRESS";
        float amount = 0.1f;
        string comment = "Payment for services";
        TGMiniAppGameSDKProvider.payWithTon(recipientAddress, amount, comment);
    }

    void OnDestroy()
    {
        if (sdkProvider != null)
        {
            sdkProvider.OnContactReceived -= HandleContact;
        }
    }

    private void HandleContact(TMARequestedContact contactInfo)
    {
        Debug.Log("Received Contact: " + contactInfo.contact.firstName + " " + contactInfo.contact.lastName);
    }
}

• When calling these methods from within Unity, make sure you are running in a WebGL build and the Telegram MiniApp environment is correctly set up.
• Ensure that TGMiniAppGameSDKProvider is present and active in the scene to handle events and callbacks.
• Non-static events require an instance of TGMiniAppGameSDKProvider to subscribe. Avoid using the class name directly for event handlers.