iOS - Q2 Lifecycle Module

note

To receive Q2 lifecycle events, a proper implementation of the Q2LifecycleModule protocol is required. Q2MobileCore will interact with your module for various Q2-specific lifecycle events.

The Q2LifecycleModule interface is used when creating a module that needs to respond to Q2-specific lifecycle events. This module provides callbacks for various authentication and navigation states including login, logout, and landing page navigation.

Q2 Lifecycle Events

The module receives notifications for the following events:

Authentication Events

• userDidSet(username:) - Notifies the username, which was set by the user during the authentication
• userDidLogin(attributes:) - Notifies that user authenticated successfully
• userFailedLogin(error:, attributes:) - Notifies that user authentication failed along with reason
• userDidLogout(attributes:) - Notifies that user did logout from the host app

Navigation Events

• appDidHitLandingPage() - Notifies that application successfully navigated to the initial landing page after authentication
• postLoginTransition(_:) - Notify module the user login finished processing and the user should be redirected to the configured landing page
• nativeLoginVisibilityChanged(visible:) - Notifies module about a change in the native login view visibility

System Events

• userThemeUpdated() - Informs the module the user theme has been updated or changed
• localizationDataChanged(_:) - Informs the module values in the localization source have been updated

Logging Events

• log(_:level:) - Logs an app message to help debug or provide details about an issue
• logEvent(_:attributes:) - Logs an expected user experience event related to a native functionality within the app
• logError(error:, attributes:) - Logs an error about unexpected behavior that could be analyzed later

Protocol Definition

Q2LifecycleModule Protocol

/// A type that handles events related to Q2 application lifecycle.
public protocol Q2LifecycleModule: LifecycleModule {

    /// Notifies the username, which was set by the user during the authentication.
    /// - Parameter username: Username used during authentication.
    func userDidSet(username: String)

    /// Notifies that user authenticated successfully.
    /// - Parameter attributes: Dictionary containing additional attributes about the authentication request.
    func userDidLogin(attributes: [String: Any]?)

    /// Notifies that user authenticated failed along with reason.
    /// - Parameters:
    ///   - error: Error object generated during the error.
    ///   - attributes: Dictionary containing additional attributes about the authentication request.
    func userFailedLogin(error: Error?, attributes: [String: Any]?)

    /// Notifies that application successfully navigated to the initial landing page after authentication.
    func appDidHitLandingPage()

    /// Notifies that user did logout from the host app.
    /// - Parameter attributes: Dictionary containing additional attributes about the authentication request.
    func userDidLogout(attributes: [String: Any]?)

    /// Logs an app message to help debug or provide details about an issue
    /// - Parameters:
    ///   - message: Message to log.
    ///   - level: Instance of `LogLevel`
    func log(_ message: String, level: LogLevel)

    /// Logs an expected user experience event related to a native functionality within the app.
    /// - Parameters:
    ///   - name: Name of the event.
    ///   - attributes: Attributes about the event.
    func logEvent(_ name: String, attributes: [String: Any]?)

    /// Logs an error about unexpected behavior that could be analyzed later.
    /// - Parameters:
    ///   - error: Instance of `Error`.
    ///   - attributes: Attributes of the error object.
    func logError(error: Error, attributes: [String: Any]?)

    /// Informs the module the user theme has been updated or changed
    func userThemeUpdated()

    /// Informs the module values in the localization source have been updated. Those can be triggered on a change of locale or strings update.
    func localizationDataChanged(_ currentLocale: String)

    /// Notify module the user login finished processing and the user should be redirected to the configured landing page
    /// - Parameters:
    /// - capabilities: User capabilities at the time of the event
    func postLoginTransition(_ capabilities: [String: Any?])

    /// Notifies module about a change in the native login view.
    /// When `visible` is false, the UUX platform will be visible in a `WKWebView`.
    /// - Parameter visible: Login view visible or hidden.
    func nativeLoginVisibilityChanged(visible: Bool)
}

Implementation

There are two ways to implement a Q2LifecycleModule depending on your needs:

Option 1: Inherit from Q2ModuleBase (Recommended)

If your module inherits from Q2ModuleBase, you only need to override the methods required for your specific functionality. This approach provides default implementations for all protocol methods, making your code cleaner and more focused.

Q2LifecycleModule Implementation with Q2ModuleBase

import Q2ModuleInterface

class Q2CustomModule: Q2ModuleBase {

    override func userDidSet(username: String) {
        print("Q2CustomModule: userDidSet(\(username))")
    }

    override func userDidLogin(attributes: [String: Any]?) {
        print("Q2CustomModule: userDidLogin(\(attributes ?? [:]))")
        // Add your custom login logic here
    }

    override func appDidHitLandingPage() {
        print("Q2CustomModule: appDidHitLandingPage")
        // Add your custom landing page logic here
    }

    // You don't need to override other methods unless you need custom functionality
}

Option 2: Raw Implementation

For full control over all protocol methods, you can implement the Q2LifecycleModule protocol directly by creating an NSObject class that conforms to all protocol requirements.

Raw Q2LifecycleModule Implementation

import Q2ModuleInterface

class CustomQ2LifecycleModule: Q2LifecycleModule {

    var moduleDelegate: ModuleDelegate?

    var moduleDataSource: ModuleDataSource?

    // MARK: - Authentication Events

    func userDidSet(username: String) {
        print("CustomQ2LifecycleModule: userDidSet(\(username))")
    }

    func userDidLogin(attributes: [String: Any]?) {
        print("CustomQ2LifecycleModule: userDidLogin(\(attributes ?? [:]))")
    }

    func userFailedLogin(error: Error?, attributes: [String: Any]?) {
        print("CustomQ2LifecycleModule: userFailedLogin - error: \(String(describing: error)) - attributes: \(attributes ?? [:])")
    }

    func userDidLogout(attributes: [String: Any]?) {
        print("CustomQ2LifecycleModule: userDidLogout(\(attributes ?? [:]))")
    }

    // MARK: - Navigation Events

    func appDidHitLandingPage() {
        print("CustomQ2LifecycleModule: appDidHitLandingPage")
    }

    func postLoginTransition(_ capabilities: [String: Any?]) {
        print("CustomQ2LifecycleModule: postLoginTransition(\(capabilities))")
    }

    func nativeLoginVisibilityChanged(visible: Bool) {
        print("CustomQ2LifecycleModule: nativeLoginVisibilityChanged(visible: \(visible))")
    }

    // MARK: - System Events

    func userThemeUpdated() {
        print("CustomQ2LifecycleModule: userThemeUpdated")
    }

    func localizationDataChanged(_ currentLocale: String) {
        print("CustomQ2LifecycleModule: localizationDataChanged(\(currentLocale))")
    }

    // MARK: - Logging Events

    func log(_ message: String, level: LogLevel) {
        print("CustomQ2LifecycleModule: log(\(message), level: \(level))")
    }

    func logEvent(_ name: String, attributes: [String: Any]?) {
        print("CustomQ2LifecycleModule: logEvent(\(name), attributes: \(attributes ?? [:]))")
    }

    func logError(error: Error, attributes: [String: Any]?) {
        print("CustomQ2LifecycleModule: logError(\(error), attributes: \(attributes ?? [:]))")
    }
}