Customizing SDK Behavior

Customize Onside SDK behavior using OnsideDelegate and OnsideAppearance — control UI themes, screen presentation, login routing, country code hinting, and global styling.

The OnsideDelegate protocol offers a way to customize and tune the behavior of OnsideKit to better fit the needs of your application. By adopting this protocol, you can control aspects like UI presentation, theming, and the authentication flow.

protocol OnsideDelegate: AnyObject {
    @MainActor func onside(hostWindowSceneForScreen screen: OnsideScreen) -> UIWindowScene?
    @MainActor func onside(uiThemeOverrideForScreen screen: OnsideScreen) -> OnsideUIThemeMode?
    @MainActor func onsideShouldForceLocalLoginMethods() -> Bool
    @MainActor func onsideDefaultCountryCodeAssumption() -> String?
}

To use the delegate, assign an object that conforms to the OnsideDelegate protocol to the Onside.delegate property. This is typically done at application launch.

// AppDelegate.swift
import UIKit
import OnsideKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate, OnsideDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Onside.initialize()
        Onside.callbackScheme = "com.yourapp.auth"

        Onside.delegate = self

        // Your other app setup code...

        return true
    }

    // ... Implement delegate methods below

}

Note: All delegate methods have a default implementation. You only need to implement the ones whose behavior you wish to change.

Providing a Pre-Login Country Code Hint

func onsideDefaultCountryCodeAssumption() -> String?

• Purpose: Product availability and pricing can vary by region. This method allows you to provide a country code hint to the SDK before the user has logged in. This enables OnsideKit to fetch the correct list of products and prices for the user's likely region, improving the user experience.

• When to Use: Use this if your application has its own knowledge of the user's region (e.g., from their profile or app settings) before they have authenticated with Onside.

• Return Value: A two-letter ISO 3166-1 alpha-2 country code string (e.g., "US", "DE", "GB").

• Default Behavior: If you return nil or don't implement the method, the SDK will use the user's device system region as the default.

Specifying the Host Window Scene

func onside(hostWindowSceneForScreen screen: OnsideScreen) -> UIWindowScene?

• Purpose: This method allows you to specify in which UIWindowScene the SDK's UI should be presented. This is particularly useful for applications that support multiple windows or screens.

• Parameter: screen is an enum of type OnsideScreen that tells you which specific UI the SDK is about to display:

  • .login: The user authentication screen.

  • .paymentMethodsManager: The screen for managing saved payment methods.

  • .paymentCardAdditionPipeline: The flow for adding a new bank card.

  • .purchase: The purchase flow.

• Default Behavior: If you don't implement this method or return nil, OnsideKit will automatically select the first active UIWindowScene from UIApplication.shared.connectedScenes.

Overriding the screen UI Theme

func onside(uiThemeOverrideForScreen screen: OnsideScreen) -> OnsideUIThemeMode?

• Purpose: You can use this method to force a specific UI theme (light or dark) for any screen presented by the SDK, overriding the global theme settings or the system's current appearance.

• Parameter: screen is an enum of type OnsideScreen that tells you which specific UI the SDK is about to display:

  • .login: The user authentication screen.

  • .paymentMethodsManager: The screen for managing saved payment methods.

  • .paymentCardAdditionPipeline: The flow for adding a new bank card.

  • .purchase: The purchase flow.

• Return Value: An optional OnsideUIThemeMode:

  • .light: Forces the light theme.

  • .dark: Forces the dark theme.

  • .auto: The theme will be based on the system setting.

  • nil: No override will be applied for this screen. The SDK will fall back to the theme configured globally via OnsideAppearance or, if not set, the system's theme.

• Default Behavior: The default implementation returns nil, meaning no theme override is applied.

Forcing In-App Login

func onsideShouldForceLocalLoginMethods() -> Bool

• Purpose: By default, OnsideKit attempts to redirect to the main Onside store app for a seamless login. This method allows you to disable that behavior and force the SDK to always display its own built-in login screen, requiring the user to re-verify their phone number.

• Return Value:

  • true: Disables the redirect to the Onside store app and forces the in-SDK login flow.

  • false: Enables the redirect if the Onside store app is installed and external login properly configured.

• Default Behavior: The default is false, enabling the preferred app-to-app authentication flow.

---

While the OnsideDelegate allows for fine-grained, screen-specific customizations, OnsideKit also provides a way to set global styling rules that apply to all UI elements presented by the SDK. This is done through the OnsideAppearance class.

You can access the shared appearance object via the static method Onside.appearance().

Setting the Global Theme

To define a consistent look and feel for all SDK screens, you can set a global theme mode.

func setThemeMode(_ themeMode: OnsideUIThemeMode?)

• Purpose: Sets the UI theme for all screens managed by OnsideKit.

• Parameter: themeMode is an optional OnsideUIThemeMode enum:

  • .light: Forces the light theme for all SDK UI.

  • .dark: Forces the dark theme for all SDK UI.

  • .auto: The UI will adapt to the user's current system-wide appearance setting (Light or Dark Mode).

  • nil: Resets the theme setting. Currently presented UI is not affected but setting nil.

The best place to configure this is at application launch, for example, in your AppDelegate.

Example: Forcing a dark theme for all OnsideKit screens.