Home

iOS SDK Integration Guide

Important

iOS SDK now has a minimum supported version of iOS 12 (it will not crash on iOS 12), but iOS 13 and above (including 13) are required for proper event tracking and popup functionality.

This guide explains where and when each method should be used, along with a sequence diagram that visualizes the overall flow.

1. Debug Logs and SDK Initialization

• Enable Debug Logs

  • When: Before calling OmniSegment.initialize
  • Purpose: Helps during development and debugging by logging the SDK’s internal processes and the payloads being sent.

• Initialize SDK

  • When: After enabling debug logs and before triggering any events with trackEvent
  • Purpose: Sets up the SDK with your API key and iOS TID.

2. Override Default App and Device Information

• setBundleId, setBundleVersion, setAppName, setDeviceId

  • When: After initialization and before any trackEvent calls
  • Purpose: Override the default values (such as Bundle Identifier, Version, App Name, and Device ID) with your own values.

• Set Firebase Cloud Messaging (FCM) Token

  • When: After SDK initialization and before tracking events (if push notifications are needed)
  • Purpose: Provides the FCM token to the SDK for push notifications.

3. User Identity Management

• LOGIN and LOGOUT

  • When: On user interaction (e.g., when the login/logout button is tapped)
  • Purpose:
    • LOGIN: Call when the user logs in and you want to track the login event (this sets the user ID).
    • LOGOUT: Call when the user logs out and you want to track the logout event.

• SET USER UID and CLEAR USER UID

  • When: Before tracking events, depending on the user’s login state
  • Purpose:
    • SET USER UID: Ensures that events include the uid when the user is logged in.
    • CLEAR USER UID: Ensures that events do not include the uid when the user is logged out.

4. WebView Management

If your app includes a WebView and you need to track events within it:

• Managing WebView Document Location

  • When: In apps that contain a WebView
  • Purpose: Allows you to override the default document location in WebView events or reset it back to default.

• Integrate OmniSegment SDK with WebView Pages

  • When: When configuring your WKWebView
  • Purpose: To include the OmniSegment content controller in your web view configuration for proper event tracking.

5. Popup and Current Page Management

• Set Popup Redirect Callback

  • When: When your popup requires a custom URL redirection
  • Purpose: Allows you to define a callback function to handle the redirection behavior.

• Set Current Page

  • When: Every time a user navigates to a new page
  • Purpose: Updates the current page context so that popups know the current page name.

6. Event Tracking

• When: After all the above configurations are completed
• Purpose: To send tracked events (using built-in or custom events) to the OmniSegment server.

Sequence Diagram

Below is a Mermaid sequence diagram that visualizes the overall flow:

sequenceDiagram
    participant Dev as Developer/App
    participant SDK as OmniSegment SDK
    participant Web as WebView

    %% Step 1: Debug and Initialization
    Dev->>SDK: enableDebugLogs(true)
    Dev->>SDK: initialize("YOUR_API_KEY", tid:"YOUR_iOS_TID")
    
    %% Step 2: Set App/Device Info & FCM Token
    Dev->>SDK: setBundleId("your.bundle.id")
    Dev->>SDK: setBundleVersion("1.0.0")
    Dev->>SDK: setAppName("YourAppName")
    Dev->>SDK: setDeviceId("your-device-id")
    Dev->>SDK: setFCMToken("your-fcm-token")
    Note right of SDK: (Trigger appOpen() after FCM setup)
    
    %% Step 3: User Identity Management
    alt User logs in
        Dev->>SDK: login(uid:"user_uid")
        Note right of SDK: uid is set for tracking
        Dev->>SDK: setUid(uid:"user_uid")
    else User is not logged in
        Dev->>SDK: clearUid()
    end
    
    %% Step 4: Popup and Page Management
    Dev->>SDK: setCurrentPage("HomePage")
    Dev->>SDK: setPopupRedirectCallback(callback)
    
    %% Step 5: WebView Management (if applicable)
    Dev->>Web: Load web content
    Web->>SDK: setWebViewLocation("custom_location")
    Web->>SDK: resetWebViewLocation() 
    
    %% Step 6: Event Tracking
    Dev->>SDK: trackEvent(.search(label:"search query"))

Loading