App link for token registration/reset-password/set-password

[coldlink]

Problem: Readers becoming registered in their phone browser rather than the app

When readers register for a new account via the Guardian Live app (and soon the Feast app), some readers are finishing their registration process in their mobile browser, rather than in the app.

When a reader taps the ‘Complete registration’ button in their verification email, depending on their device settings, across both iOS and Android, the link will either open in the Guardian app (happy path) or in their phone browser (unhappy path).

A possible solution is if a reader’s device directs them to their mobile phone browser rather than back to the app, display a screen, similar to Substack’s (see below) directing them back to the Guardian app.

This would involve setting up a deep-link that the app would handle, using the x-gu:// protocol which I think is what's used elsewhere at the guardian: https://github.com/search?q=org%3Aguardian+x-gu%3A%2F%2F&type=code

So the steps would be as follows:

1. When the user clicks the clicks the link in the email inbox, it opens up in the browser instead of the app
2. The browser will make a request to gateway using this link
3. Gateway returns a page which says something along the lines of "click on this link to open it in the app to complete registration/reset-password/set-password" i. this link uses the deep link protocol for guardian apps, which is something like x-gu://handle/deep-link?welcome_token=token (the deep link name is TBD)
4. User clicks deeplink CTA
5. This opens within the app
6. The app extracts the token from the deeplink and passes it in the same way to the SDK as handled before for registration/reset-password/set-password depending on type of token

Modifying the chart from https://github.com/guardian/gateway/blob/main/docs/okta/native-apps-integration-guide.md#registration-and-reset-password showing only the problem section

sequenceDiagram
autonumber

participant NativeLayer
participant InAppBrowserTab
participant DefaultBrowser
participant Gateway
participant EmailInbox

  note over InAppBrowserTab: At this point the user<br>has to navigate to the email inbox<br/>and click the activation<br>link to activate their account.<br>The app should intercept this link<br>and handle the activation<br>process.<br>However this doesn't always work so we need<br>two options.
  note over EmailInbox: user navigates to inbox and clicks CTA
  alt [https interception works]
    EmailInbox ->> NativeLayer: Click link in email /welcome/{prefix}_{activationToken}<br>https link is intercepted by system and opens up in app 
    note over NativeLayer: Intercept activation link<br/>in-app browser tab to app. <br>Extract token from link<br/>and use SDK methods
  else [https interception doesn't work]
    EmailInbox ->> DefaultBrowser: Click link in email /welcome/app-link/{prefix}_{activationToken}<br>https interception doesnt work, so opens in default browser/email in app browser
    note over DefaultBrowser: currently this breaks the link to the app<br>as it goes through the whole onboarding process<br>and user ends up signed into the mobile browser but not the app<br> hopefully the next step demonstrates what we want to do to fix this
    DefaultBrowser ->> Gateway: Request<br>GET /welcome/app-link/{prefix}_{activationToken}
    note over Gateway: If we see this request to gateway we know<br>that this link didn't open in the app<br>so we show a page with a deep link telling user<br>to click this link to open in app
    Gateway ->> DefaultBrowser: Return page with CTA deep link<br>x-gu://some/deep-link-to-app?token=xxx&type=welcome
    note over DefaultBrowser: user clicks the CTA
    DefaultBrowser ->> NativeLayer: Request x-gu://some/deep-link-to-app?activation_token=xxx
    note over NativeLayer: intercept this deep link<br>extract token from link<br>and use SDK methods
  end

  NativeLayer ->> InAppBrowserTab: Call `signin`/`signInWithBrowser`<br/>to perform<br />Authorization Code Flow with PKCE<br>pass `activation_token` as additional parameter<br>or `reset_password_token` for reset password<br>or `set_password_token` for set password
  note over InAppBrowserTab: rest of the flow continues as before

[coldlink]

We're not going to be doing this anymore, as it relied heavily on apps engineers helping us out, and they don't have the resource to do this.

We're looking at passcodes (and passwordless) as a longer term solution, and in the meantime we'll show a page instructing users how to get back into the app.