TikTok - hippogamesunity/SimpleSignIn GitHub Wiki

Welcome to Simple TikTok Sign-In wiki!

The asset provides TikTok sign-in with OAuth 2.0 for Android, iOS, Windows, macOS, Universal Windows Platform (UWP) and WebGL apps made with Unity. You can also get access tokens to make REST API calls.

Benefits

Cross-platform user auth for cross-platform games and apps
No plugins, no 3rd party libs, no dependencies
No impact to build size
Get access tokens to make API calls
More security for client-server apps (get an access token on a client, get all user data on a server to avoid tampering)
SFSafariViewController is used on iOS (required by App Store review)
Deep linking for Windows (UNITY_STANDALONE_WIN)

Terminology

Please visit Terminology section

Understanding how it works

Generic workflow (for platforms that support deep linking):
- Your app navigates users to TikTok Authorization Endpoint using a default web browser
- Users perform sign-in
- TikTok Authorization Endpoint redirects users to Redirect URI (this can be a deep link when possible) and provides an authorization code to the app (as URI parameters)
- The app is activated and obtains code
- The app exchanges code for access token
- The app requests user info with access token (name, avatar and other data according access scopes defined)
Deep linking for Android and iOS:
- Redirect URI is a deep link which activates the app and provides code in URI parameters
Loopback flow for Editor and Desktop:
- Redirect URI is http://localhost:PORT/ with a random unused port
- The app listens to localhost using System.Net.HttpListener
- The app obtains code and asks a user to close the browser tab and to return to the app
- Further workflow is the same (exchanging code for access token, requesting user data)
Middleware flow for WebGL:
- OAuth Redirect to Authorization Middleware is used to temporary save code
- The app obtains code from Authorization Middleware with a POST request
- Further workflow is the same (exchanging code for access token, requesting user data)
For Windows (Standalone), Universal Windows Platform (UWP) and macOS (OSX):
- TikTok doesn't support deep links for these platforms (even if they support deep linking)
- Desktop app type should be used by design (with Loopback flow)
- As a workaround, we can use Web app type and Authorization Middleware to activate your app with deep linking.

Preconditions

For Android, iOS, macOS, Windows and UWP (platforms that support deep linking): COME UP WITH your Custom URI scheme (or Protocol). In my example it is simple.oauth, but it can be jelly.bean or myapp (note that Custom URI scheme is not the same as your actual package name or bundle id). For UWP, it MUST contain the period symbol . and small alphanumeric symbols only (no spaces, no undercores).
For Android, iOS, UWP: enable deep linking as described below (or refer to Unity documentation).
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
For Editor: Set Allow downloads over HTTP = Always allowed (Unity 2022+)

Setup steps

Visit TikTok for developers
Create a new app and fill app details required
Switch to Sandbox to test sign-in without completing app review
Copy Client key and Client secret
Go to Platforms section and enable the following Platforms: Web, Desktop (DO NOT ENABLE Android and iOS)
- fill all information required (most fields can be set to 0 for Sandbox)
- for Web/Desktop: fill Web/Desktop URL (can be 0 for Sandbox)
- add Login Kit to Products
- set Redirect URI for Web: https://hippogames.dev/api/oauth/redirect (you can deploy your own Authorization Middleware later)
- set Redirect URI for Desktop: http://localhost:*/
- AGAIN: Android and iOS should be unchecked even if you build for these platforms
Go to Scopes and add extra scopes (optionally)
Go to Sandbox settings and add your account (you can add multiple accounts)
- Note: Sandbox will work for these accounts only
Return to Unity, select SimpleSignIn/TikTok/Resources/TikTokAuthSettings
- set Client Key and Client Secret (refer to step 4)
- set Custom Uri Scheme (refer to Preconditions)
- set Access Scopes (should be the same as in app configuration)
- set User Fields (they should be covered by your access scopes)

Checklist

Custom URI scheme is picked, and it has a different value than simple.oauth
Custom URI scheme is set in 3 places: [1] TikTok for developers (Redirect URI), [2] Resources/TikTokAuthSettings, [3] your application manifest (AndroidManifest.xml for Android, Supported URL schemes for iOS, Protocol for UWP)
Client Key, Client Secret and other settings are changed inside Resources/TikTokAuthSettings

Usage

Check our Example scene and C# code of Example.cs
Create an instance of TikTokAuth
Call TikTokAuth.SignIn or TikTokAuth.GetAccessToken
Create OnSignIn or OnGetAccessToken callbacks
Build and test
Write a review on the Asset Store :)

Best practices

Call TikTokAuth.SignIn with caching: true to return cached UserInfo
Call TikTokAuth.SignIn with caching: false to request UserInfo from TikTok
Call TikTokAuth.GetAccessToken instead of TikTokAuth.SignIn if you need an access token only (and don't need UserInfo)
You can use TikTokAuth.SavedAuth to get TokenResponse or UserInfo (don't forget to check all values for null)
Call TikTokAuth.SignOut when Sign out button is pressed (you can revoke the access token if needed)
Disable debug logs for production by setting TikTokAuth.DebugLog = false

Next steps (optional)

Complete app review (the most complicated step) and switch to Production (don't forget to provide valid app details)
You can add extra access scopes in Resources/TikTokAuthSettings (UserInfo class should be extended as well)
If you have a backend (server), send TokenResponse to it (to avoid tampering user data when sending from clients to your server)
For Editor and Windows (optional), you can modify StandaloneTemplate.html (used by Loopback flow) to edit the message "Success! Please close the browser tab and return to the app."
For Windows, check Settings for Windows
For WebGL, consider deploying your own Authorization Middleware
You can use this asset with async methods, just refer to TikTokAuthAsync.cs for examples

Can I trust Authorization Middleware? Is it secure to use a 3rd party service?

Authorization Middleware can't exchange code for access token without knowing both client secret and code verifier. Only the app itself can exchange code for access token.
It's recommended to deploy your own trusted Authorization Middleware to handle sensitive data. Please refer to Authorization Middleware article.

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

Please visit Common issues section
TikTok no longer supports Deep Links (they now use Android App Links and iOS Universal Links, so you may see the following error: Redirect Uri: Enter a valid Android redirect uri beginning with https://. There are 2 solutions:
- Easy: to avoid complicated setup, the asset may use Web app type for Android and iOS and Authorization Middleware that receives oauth codes from TikTok and then activates your app with deep linking. The main issue that there may be problems with app review. Select Flow For Android / iOS = Authorization Middleware in TikTokAuthSettings.
- Complicated: enable Android and iOS app types, fill all required fields and then setup Android App Links and iOS Universal Links. This is the most complicated part and you'll need your own domain for this. For Android, you'll also need to modify AndroidManifest (set android:scheme="https" and android:host="yourdomain.com"). Select Flow For Android / iOS = Android / iOS in TikTokAuthSettings.

OAuth flow setup for Windows, UWP and macOS

You can switch Loopback / Authorization Middleware in TikTokAuthSettings.