Skip to content

Telegram

Jump to bottom
Nate River edited this page Jun 3, 2024 · 2 revisions

Welcome to Simple Telegram Sign-In wiki!

The asset provides Telegram sign-in for Android, iOS, Windows, macOS, Universal Windows Platform (UWP) and WebGL apps made with Unity.

Benefits

  • Cross-platform user auth for cross-platform games and apps
  • No plugins, no 3rd party libs, no dependencies
  • No impact to build size
  • SFSafariViewController is used on iOS (required by App Store review)
  • Deep linking for Windows (UNITY_STANDALONE_WIN)

Terminology

Understanding how it works

  • Your app navigates users to Authorization Middleware using a default web browser (embedded webviews are not allowed)
  • Authorization Middleware shows Telegram Widget or performs silent auth call (depending on ShowTelegramWidget setting)
  • Users perform sign-in inside Telegram popup
  • Telegram Widget returns auth data to Authorization Middleware
  • Authorization Middleware redirects auth data to your app with deep linking (when possible)
  • Authorization Middleware returns data by app request when deep linking is not possible (Editor, WebGL)

Preconditions

  • For Android, iOS, macOS, Windows and UWP (platforms that support deep linking): COME UP WITH your Custom URI scheme (or Protocol). It MUST contain the period symbol . and small alphanumeric symbols only (no spaces, no undercores). In my example it is simple.oauth, but it can be jelly.bean (note that Custom URI scheme is not the same as your actual package name or bundle id).
  • For Android, iOS, UWP: enable deep linking as described in Unity documentation or as described below.
  • For Android: create AndroidManifest.xml inside Assets/Plugins/Android/, SET your Custom URI scheme inside, like <data android:scheme="simple.oauth" />. You can use AndroidManifestExample.xml from the asset as an example, just copy, rename and edit. AGAIN, DON'T FORGET TO REPLACE simple.oauth with your Custom URI scheme!
  • For iOS and macOS: navigate to Player Settings > Other > Configuration and add your Custom URI scheme to Supported URL schemes. In Xcode, make sure that the URL scheme is added (Register your URL scheme).
  • For Universal Windows Platform: navigate to Player Settings > Publishing Settings and set Protocol (it MUST contain a period symbol, for example simple.oauth), then enable InternetClient in Capabilities.
  • For Windows: navigate to Player Settings and enable Resolution and Presentation > Force Single Instance and set Other Settings > Api Compatibility Level = .NET Framework

Setup steps

  1. Add @BotFather on Telegram
  2. Create a new bot with /newbot command, provide name and username
  3. Execute /setdomain command and add https://hippogames.dev (Authorization Middleware)
  4. Configure Resources/TelegramAuthSettings.asset
    • Set Bot Id (digits only, without #) which is displayed in Telegram conversation with your bot
    • Set Bot Name (without @) which is username from step 2
    • Set Custom Uri Scheme picked in Preconditions
    • Set ShowTelegramWidget if needed (otherwise silent auth will be called)

Checklist

  • Custom URI scheme is picked, and it has a different value than simple.oauth
  • Custom URI scheme is set in 2 places: [1] Resources/TelegramAuthSettings.asset, [2] your application manifest (AndroidManifest.xml for Android, Supported URL schemes for iOS, Protocol for UWP)
  • Bot Name is copied to Resources/TelegramAuthSettings.asset

Usage

  1. Check our Example scene and C# code of Example.cs
  2. Create an instance of TelegramAuth
  3. Call TelegramAuth.SignIn
  4. Create OnSignIn callback as the first argument for TelegramAuth.SignIn to obtain UserInfo
  5. Build and test
  6. Write a review on the Asset Store :)

Best practices

  • Call TelegramAuth.SignIn with caching: true to return cached UserInfo
  • Call TelegramAuth.SignIn with caching: false to request UserInfo from Telegram each time
  • You can use TelegramAuth.SavedAuth to get UserInfo (don't forget to check all values for null)
  • Call TelegramAuth.SignOut when 'Sign out` button is pressed (optional)
  • Disable debug logs for production by setting TelegramAuth.DebugLog = false

Next steps (optional)

  • It's recommended to deploy your own trusted Authorization Middleware to handle sensitive data. Please refer to Authorization Middleware article.
  • You can use this asset with async methods, just refer to TelegramAuthAsync.cs for examples.

Notes

  • Please refer to User data disclosure
  • Don't use default credentials that come with the asset in production, they are for test purposes only and can be disabled/blocked
  • Check Manual cancellation if needed

Known issues

  • Common issues
  • When ShowTelegramWidget is set to False some browsers may block popups or promt a user

Support

Links

Clone this wiki locally