Deep Linking in Unity (iOS & Android) for OAuth Redirects

Deep linking is the piece that makes OAuth work in a game instead of just a website. The login happens in a browser, but the result has to end up inside your running Unity build — and a URL alone can't reach into an app. This is how that jump works on iOS and Android, and where it tends to break.

Why a game needs it at all

OAuth was built for the web. The player leaves for a browser, approves, and the provider redirects to a redirect URI. On a website that's the end of the story — the browser is already the app. In a game it isn't. You need to get from "a web page just loaded with the login result" to "my Unity game is in the foreground, holding that result." A deep link is that bridge: a URL that, when opened, launches your specific app instead of a web page.

The three ways to open your app

There are three mechanisms, and they trade convenience against trust:

Custom URL scheme. You register something like mygame://auth, and opening that URL launches your game. It's the simplest option and works on every platform. The catch is that schemes aren't owned — another app can register the same one, so it's convenient but not tamper-proof.

iOS Universal Links. A normal https:// link that opens your app instead of Safari, tied to a domain you control. It can't be hijacked, because the OS verifies the link against a file (apple-app-site-association) hosted on your domain. The cost is hosting that file and configuring the associated domain.

Android App Links. The Android counterpart — verified https:// links backed by an assetlinks.json file on your domain, so only your app can claim them.

The common pattern is to ship the custom scheme first because it's the least setup, then add verified links when you want the stronger guarantee. If you're building a purely web (WebGL) target, none of this applies — the return is an ordinary web redirect back to the page, no deep link required. For how this plays out across every target at once, see cross-platform login in Unity.

Where it breaks

Deep links fail quietly, which makes them annoying to debug. The usual causes:

• The scheme isn't registered. The link fires, nothing happens, because the manifest or Info.plist never declared it.
• A scheme collision. Two apps claim the same custom scheme and the wrong one opens.
• Verified links not actually verified. Universal Links and App Links silently fall back to opening the browser when the domain verification file is missing, unreachable, or malformed.
• No plan for a missing app. If the game isn't installed or can't open, a naive flow just dead-ends.

How Oathwall handles the return trip

Oathwall keeps the provider-facing side fixed — every provider redirects to https://sso.oathwall.com/auth/callback — and manages the game-facing deep link for you. In the dashboard you set your app's scheme, path, package, and a fallback URL. After the token exchange, Oathwall's redirect page carries a single-use login ticket and launches the deep link into your game; if the app can't open, it uses the fallback instead of failing silently.

On the Unity side, the SSO Login Kit injects the intent filter into the Android manifest and the URL scheme into the iOS Info.plist at build time, so the deep link that delivers the ticket is registered without you hand-editing platform files. When the game receives the link, the kit reads the ticket, exchanges it for the session, and calls your OnLoginSuccess — the deep link is invisible to your game code:

using PixitGames.SSOLoginKit;

public class LoginManager : SsoClientBase
{
    // StartLogin opens the browser; the deep link back into
    // the game is registered and handled for you.
    public void OnLoginButton() => StartLogin("google");

    protected override void OnLoginSuccess(LoginResult user)
    {
        Debug.Log($"Back in the game as {user.name}");
    }
}

To see the address the provider redirects to first, read what a redirect URI is, and the Unity authentication guide shows the full round trip from button to signed-in player.