External Login

Sign in with your app's account identifier, configure fallback login, and handle the purchase restrictions for external profiles.

OnsideKit can create a session using your app’s account identifier, without first presenting the regular Onside login flow. Configure Onside.externalLoginDelegate to supply that identifier when login is needed.

External login is optional and disabled by default. It is separate from app-to-app login through the Onside store app.

Configure the native delegate

protocol OnsideExternalLoginDelegate: AnyObject {
    @MainActor func onsideExternalAccountToken() async -> String?
}

The returned string is your host account’s external_user_id. Despite the method name, this is not an Onside access token or refresh token. Return the identifier for the current user, or nil when there is no account to use. An empty string is passed through to the service; use nil to request fallback.

import OnsideKit

@MainActor
final class ExternalLoginProvider: OnsideExternalLoginDelegate {
    var currentUserID: String?

    func onsideExternalAccountToken() async -> String? {
        currentUserID
    }
}

@MainActor
final class OnsideIntegration {
    // The SDK holds this delegate weakly; retain it in a long-lived owner.
    private let externalLogin = ExternalLoginProvider()

    func configure(currentUserID: String?) {
        Onside.initialize()
        externalLogin.currentUserID = currentUserID
        Onside.externalLoginDelegate = externalLogin
    }
}

Keep the OnsideIntegration instance alive, update the provider when your app’s account changes, and configure Apple Pay before starting purchases. The async delegate can await your account service without blocking the main actor.

Login order and fallback

Explicit Onside.requestLogin() and actions that require a missing session use this sequence:

1. If an external delegate is assigned, request the current account identifier.

2. With a non-nil identifier, the SDK creates a session and loads the resulting profile.

3. If the identifier is missing or session creation fails, use OnsideDelegate.onsideLoginMethod() — .auto by default, or .local if selected.

4. If the session was created but loading its profile fails, fall back to the in-SDK phone login.

The identifier is requested for each external login attempt; assigning a delegate does not replace an already authenticated session. On-demand operations reuse an existing profile. Keep the callback URL setup from Initializing the SDK for .auto fallback through the Onside store app.

Returning .local from onsideLoginMethod() does not disable external login. To disable future external attempts, set Onside.externalLoginDelegate = nil. To switch an existing external session to regular Onside login, also log out and start login again. Onside.logout() does not sign the user out of your app’s account system.

Product and payment support

Restrictions apply to the authenticated profile, not simply to the presence of a delegate. If external login falls back to a regular Onside account, regular purchase rules apply.

Capability	External profile
Consumable purchases	Supported through Apple Pay in the full OnsideKit build.
Non-consumables and subscriptions	Excluded from product results; buying a previously loaded product fails with .notSupportedForExternalLogin.
Saved bank cards and payment-method switching	Unavailable.
Payment methods manager	Fails with .notSupportedForExternalLogin.
Consumable purchase without Apple Pay	Fails with .applePayRequired before enqueueing. This includes OnsideKitLite.

A products response lists filtered products in unsupportedProductIdentifiers, separately from invalidProductIdentifiers. Refresh products after login or any storefront change. Handle both purchase errors in the add completion; a rejected attempt has no transaction to finish.

The public storefront exposes id and countryCode, not an isExternal property. Use the returned products and typed errors to handle capabilities. Do not infer the current profile type solely from whether you assigned a delegate.

After a successful external-profile purchase, OnsideKit presents a receipt reminder (OnsideScreen.externalAccountNotification) with receipt and skip actions. The reminder explains that the purchase does not appear in Onside Store automatically and offers a receipt as proof of payment. Your observer still processes and finishes the transaction in the usual way.

Account correlation and validation

OnsidePayment.appAccountToken remains a separate optional value for correlating purchases with your backend. Returning an external account identifier does not populate it automatically. Set it on the payment when your integration uses it, and follow the normal purchase validation flow.

JavaScript and testing

• JavaScript — register externalAccountToken after bridge initialization, then await setExternalLoginEnabled(true).

• Local testing — leave the external delegate disabled and select local login for an offline simulation. A .storekit file does not simulate a real external profile or its restrictions; validate those against the service on an iOS build.