User account

For OnsideKit to function fully, the user must be authenticated. An authenticated account securely stores payment methods, purchase history, and ensures that product availability and pricing are accurate for the user's region.

How Authentication Affects Product Availability

The user's region is crucial for determining which products are available and at what price. The login status directly impacts how this region is determined:

• When Logged In: The region associated with the user's Onside account is used. This is the most accurate source of truth.

• When Logged Out: The SDK uses a fallback mechanism to estimate the user's region:

  1. It first calls the onsideDefaultCountryCodeAssumption() delegate method. If you provide a country code here, it will be used.

  2. If the delegate method returns nil, the SDK will use the device's system region as the default.

Initiating the Login Flow

Authentication in OnsideKit can be initiated in two ways: explicitly by your code, or implicitly by the SDK when a user attempts an action that requires a valid session.

1. Explicit Initiation

You can trigger the login flow at any time by calling the static Onside.requestLogin() method. This is the recommended approach for UI elements like a dedicated "Log In" button.

2. Implicit Initiation (Automatic)

OnsideKit is designed to be smart. You don't always need to check if the user is logged in before calling certain functions. If a user is not authenticated when they try to perform a protected action, the SDK will automatically present the login flow first. Once the user successfully logs in, the SDK will proceed with the original action.

The login flow will be triggered implicitly when you call methods to:

• Initiate a product purchase.

• Display the payment methods manager screen.

• Start the flow for adding a new payment card.

This simplifies your code! You can simply call the purchase method, and OnsideKit handles the "is user logged in?" check for you.

Understanding the Authentication Flows

Regardless of whether the login is initiated explicitly or implicitly, OnsideKit will use one of the following two authentication flows:

• App-to-App Authentication (Preferred): If the Onside store app is installed and OnsideKit correctly configured, the user is redirected to Onside store for a seamless login and then returned to your app.

• In-SDK Authentication (Fallback): If the Onside app isn't available or the app-to-app flow is disabled via the onsideShouldForceLocalLoginMethods() delegate method, the SDK presents its own UI for phone number verification.

Checking the Current Authentication Status

While OnsideKit can handle login implicitly, you will often want to check the user's authentication status to customize your UI.

The user's session is represented by the storefront object on the payment queue. A non-nil storefront indicates an active, authenticated session.

There are two ways to work with the storefront: by manually checking its current state, or by observing changes in real-time.

1. Manually Checking the Current Status

func updateUserUIBasedOnLoginStatus() {
    let isUserLoggedIn = Onside.paymentQueue().storefront != nil
    
    if isUserLoggedIn {
        // User is logged in. Show account-specific UI.
        loginButton.isHidden = true
        
        // You can also access the user's region from the storefront
        if let userRegion = Onside.paymentQueue().storefront?.countryCode {
            print("User is authenticated. Storefront region: \(userRegion)")
        }
    } else {
        // User is not logged in. Show a login button.
        loginButton.isHidden = false
        print("User is not authenticated.")
    }
}

2. Observing Changes in Real-Time

For a more robust and reactive approach, you can observe changes to the storefront directly. This is the best way to ensure your UI is always in sync with the user's authentication state.

To do this, you must add an observer that conforms to the OnsidePaymentTransactionObserver protocol to the payment queue. The SDK will then notify your observer whenever the storefront changes.

import UIKit
import OnsideKit

class MyViewController: UIViewController, OnsidePaymentTransactionObserver {

    override func viewDidLoad() {
        super.viewDidLoad()
        // Add self as an observer to the payment queue
        Onside.paymentQueue().add(self)
    }

    func onsidePaymentQueueDidChangeStorefront(_ queue: OnsidePaymentQueue) {
        print("Storefront changed! New storefront: \(String(describing: queue.storefront))")
        // Now, update your UI based on the new state.
        updateUserUIBasedOnLoginStatus()
    }
    
    ...
}

Logging Out

To manually end the current user's session, call the Onside.logout() method. This is useful for implementing a "Sign Out" button in your app's user profile or settings screen.

Calling this method will clear all local authentication data for the current user. After a successful logout, Onside.paymentQueue().storefront will become nil, and any action requiring authentication (like making a purchase) will automatically trigger the login flow again.