Launching the iOS SDK

On iOS, launching Cheggout means constructing a CheggoutApp. There is no separate launch() call: the initialiser takes the identity, the options and the exit closure, and presenting the SDK is a side effect of creating it. Hold a strong reference to the instance, and clear it in the exit handler.

The launch flow

Your app never mints the session. GenerateSessionInfoV2 needs a signed envelope, which needs your RSA private key, which must stay on your servers.

Initialisers

Two initialisers are documented. The short form sets up the SDK against a channel; the full form carries the user's identity and launch options.

// Channel-level initialisation with an exit handler
cheggoutApp = CheggoutApp(
    channelName: bankName,
    exitHandler: { _ in
        DispatchQueue.main.async { self.dismiss(animated: false) }
    }
)

// Full launch
cheggoutApp = CheggoutApp(
    userID: userID,
    sessionInfo: sessionInfo,
    accessInfo: nil,
    payload: payload,
    exitHandler: { _ in /* cleanup */ }
)

Launch parameters

Parameter	Type	Required	Description
userID	String	Yes	Any unique identifier passed during invocation from the host app — in practice, the user's virtualId.
sessionInfo	String	Yes	The session ID used to identify and track the user session, from GenerateSessionInfoV2.
accessInfo	—	No	Pass nil. TBD Its purpose and accepted values are not documented.
payload	[String: Any]?	No	Launch options. See Payload keys.
exitHandler	closure	Yes	Called when the SDK exits. This is where you clear the initialised Cheggout instance.
channelName	String	Yes (short form)	Your Cheggout channel identifier, issued at onboarding.

Unlike Android, the iOS payload is a dictionary, not a string.

Payload keys

Key	Values	Required	Description
Component	CHEGGOUT, HEALTH, PHARMA, HEALTHPACKAGE	No	Which component to launch. Defaults to CHEGGOUT.
IsEmployee	0 / 1, or Yes / No	No	Marks the user as a publisher employee so employee-specific offers apply. Treated as 0 if not sent.
DeeplinkInfo	The href from a banner, store or scratch card response	No	Redirects to an offer or store-specific page inside the SDK. Present only when the SDK is invoked from a deep link or a push notification.
Language	2-character ISO code, e.g. EN	No	Interface language.
pushnotificationID	String	No	The Firebase identifier for the logged-in user, when Cheggout manages push delivery.
customerId	String	No	A publisher-side customer reference.

let payload: [String: Any] = [
    "Component": "CHEGGOUT",
    "IsEmployee": "0",
    "Language": "EN",
    "DeeplinkInfo": "",          // set from a banner/store href on click
    "customerId": ""
]

Full example

Swift

import CheggoutBridge
import UIKit

final class ShopViewController: UIViewController {

    // Strong reference — the SDK is released in the exit handler.
    private var cheggoutApp: CheggoutApp?

    func openCheggout(virtualId: String, sessionId: String, deepLink: String = "") {

        let payload: [String: Any] = [
            "Component": "CHEGGOUT",
            "IsEmployee": "0",
            "Language": "EN",
            "DeeplinkInfo": deepLink,
            "customerId": ""
        ]

        cheggoutApp = CheggoutApp(
            userID: virtualId,
            sessionInfo: sessionId,
            accessInfo: nil,
            payload: payload,
            exitHandler: { [weak self] _ in
                DispatchQueue.main.async {
                    self?.dismiss(animated: false)
                    self?.cheggoutApp = nil        // release the instance
                }
            }
        )
    }
}

Objective-C

@import CheggoutBridge;

- (void)openCheggoutWithVirtualId:(NSString *)virtualID
                        sessionId:(NSString *)sessionID {

    NSDictionary *payload = @{
        @"Component": @"CHEGGOUT",
        @"IsEmployee": @"0",
        @"Language": @"EN",
        @"DeeplinkInfo": @"",
        @"customerId": @""
    };

    self.cheggoutApp = [[CheggoutApp alloc] initWithUserID:virtualID
                                               sessionInfo:sessionID
                                                accessInfo:nil
                                                   payload:payload
                                               exitHandler:^(NSString * _Nullable result) {
        NSLog(@"Perform additional tasks");
        // Dismiss and release here.
    }];
}

Hold the reference, and only one

Keep cheggoutApp as a property. A local variable is deallocated as soon as the function returns, and a second instance created while the first is on screen leaves you with two exit handlers racing to dismiss the same view controller. Create one, clear it on exit.

When the identifiers are wrong

There is no error callback for a bad identifier. The documented behaviour is:

Invalid IDs produce a white page

An invalid userID or sessionKey prevents the SDK from proceeding beyond the claimer page, resulting in a white page. No exception is thrown, no alert is shown, and exitHandler is not called with a reason.

Because the failure is silent, validate before you construct the instance:

• Do not launch if your backend's session call failed or returned an empty sessionId. Show your own error and offer a retry.
• Ensure the sessionId was minted for the same virtualId you are passing as userID. The session is generated from the virtual ID; a mismatched pair breaks SSO.
• Ensure channelName matches the channel your backend signed with.
• Log the userID and a hash of the session at launch so a white-page report can be traced.

Exit handling

exitHandler is a closure invoked when the SDK exits — when the user backs out of the Cheggout home page, or when a deep payment hands control back to you. Two responsibilities live there:

1. Dismiss the presented SDK, typically on the main queue.
2. Clear the initialised Cheggout instance, so it is deallocated rather than lingering.

exitHandler: { [weak self] result in
    DispatchQueue.main.async {
        self?.dismiss(animated: false)
        self?.cheggoutApp = nil
    }
}

The closure's parameter carries data in the deep payment flow: on exit, the handler receives the payment data response, Base64 encoded. If you do not use deep payment, ignore it. If you do, see Callbacks for the decoded shape.

After control returns, where the user lands is your decision, and it depends on whether your app still treats the session as live — the same rule as Android. If your app ends the session, take them to your login page; if you keep it alive using Last Activity Time or a heartbeat, take them home. The iOS heartbeat equivalent is the TrackUserActivity notification, documented in Callbacks.

Next

• SDK methods — banners, stores, points and scratch cards.
• Callbacks and notifications — completion handlers, TrackUserActivity and reveal notifications.
• Session and SSO.