Skip to content

Compliance module integration technical guide

Changes
6.3.2025 Initial version of the documentation published.

iOS Compliance Module SDK Integration Guide

Overview

This section provides step-by-step instructions for integrating the Compliance SDK as an XCFramework into your iOS project.

Prerequisites

Before integrating the Compliance SDK, ensure the following:

  • Xcode 16.0 or later.
  • Minimum deployment target: iOS 12.0+.

Follow these steps to add the Compliance SDK to your project manually.

  1. Open Xcode and your project.
  2. In the Project Navigator, select your project.
  3. Go to the General tab.
  4. Scroll to Frameworks, Libraries, and Embedded Content.
  5. Drag and drop compliancemodule.xcframework into this section.
  6. Ensure it is set to “Embed & Sign”.

Integration Steps

  1. Import ComplianceModule

Import the SDK.

Add this to any file where you need compliance functionality:

import ComplianceModule

  1. Create a ComplianceSettings Object

Initialize ComplianceSettings in AppDelegate or your main application controller:

   let complianceSettings = ComplianceSettings(
                publisherProvidedID: UUID().uuidString,  /// A unique, publisher-assigned device identifier for compliance tracking.
        )

  1. Initialize ComplianceController Object

Instantiate a ComplianceController object to manage compliance-related checks and user preferences. This is the main entry point to all compliance checks. 

import UIKit
import ComplianceModule

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    var complianceController: ComplianceController?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions:     [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        // Initialize ComplianceModule
        complianceController = ComplianceController(
            settings: settings,
            analyticsService: ComplianceAnalyticsService(),
            delegate: self
        )

        return true
    }
}

The ComplianceAnalyticsService needs to implement the AnalyticsServiceProtocol to ensure proper handling and logging of compliance-related analytics events. The send(_ event: AnalyticsEvent) function must be implemented to log and process analytics events, ensuring accurate compliance tracking.

  1. Implement ComplianceDelegate

The ComplianceDelegateProtocol is designed to notify clients about key events related to compliance data collection within the application. It provides callbacks to inform the client when the compliance module updates its internal state and when user preference collection begins or completes. This allows applications to respond accordingly and ensure seamless integration with compliance requirements.

extension AppDelegate: ComplianceDelegateProtocol {

    public func initialSubjectContextModel() -> SubjectContextModel {
        return SubjectContextModel()
    }

    public var firebaseID: String? {
        return "user-firebase-id" // Use only if needed.
    }

    public var appWindow: UIWindow? {
        return UIApplication.shared.windows.first
    }

    public var isDevelOrProdBuild: Bool {
        return false // Adjust based on the environment.
    }

    public func willCollectPreference() {
        print("ComplianceModule: Will collect preferences")
    }

    public func onStateUpdated() {
        print("ComplianceModule: State updated")
    }

    public func onPreferenceCollectionReady() {
        print("ComplianceModule: Preference collection ready")
    }

    public func onPreferenceCollected() {
        print("ComplianceModule: Preferences collected")
    }
}

  1. Create a SubjectContextModel Object

The SubjectContextModel is a struct that holds compliance-related data, including:

•   **homeCountryCode**: ISO country code (e.g., “US”, “DE”).

•   **regionOverride**: Allows manual override of the detected region.

Example: Creating SubjectContextModel

let subjectContext = SubjectContextModel(
    homeCountryCode: "US",  // Manually override detected country (if needed).
    regionOverride: "CA",   // Manually override detected region (if needed).
)

  1. Call updateState() with SubjectContextModel

The updateState function updates the compliance state based on the provided SubjectContextModel. It ensures that the compliance module reflects the latest context, and triggers a network request to retrieve the latest compliance state from the backend.

Once the SubjectContextModel is prepared, we update the compliance state by calling:

complianceController.updateState(context: subjectContext)

This triggers backend requests to fetch all required compliance data, including the preference collectors for display. Once the ComplianceModule has gathered all the necessary data, it notifies us by invoking the onPreferenceCollectionReady() method in the ComplianceDelegateProtocol.

  1. Collect User Preferences

When we receive the onPreferenceCollectionReady() callback in ComplianceDelegateProtocol, we are ready to start the data collection process. Once our application is prepared, we can trigger the display of all collectors by calling collectPreferences().

complianceController.collectPreferences()

Once the preference collection process is completed, we receive a confirmation via the onPreferenceCollected() callback inside ComplianceDelegateProtocol.

  1. Check Interest-Based Advertising (IBA) Permission

After completion, we can check whether Interest-Based Advertising (IBA) is allowed by calling:

let isIBAAllowed = complianceController.isInterestBasedAdvertisingAllowed(vendorID: "vendor_id" ).value

This returns a Bool (true or false) based on the user’s preferences.

Android Compliance Module SDK Integration Guide

Overview

This section provides step-by-step instructions for integrating the Compliance SDK into your Android project.

Prerequisites

Before integrating the Compliance SDK, ensure the following requirements are met:

  • Minimum SDK Version: 23
  • Dependency: Add compliance.aar to libs folder within your project and add the following dependency to your build.gradle: 
implementation(files("libs/compliance.aar"))

Integration Steps

1. Retrieve an Instance of Compliance

To use the Compliance SDK, retrieve an instance as follows:

val compliance: Compliance = Compliance.getInstance()

2. Create a ComplianceSettings Object

A ComplianceSettings object is required for initialization. It contains all necessary configuration details:

val complianceSettings = ComplianceSettings(
    publisherProvidedId: String, // your publisher ID 
    homeCountry: String?, // e.g., "US", "DE", can be null. If not provided, Compliance resolves it from the IP.
    buildFlavor: String?, // e.g., "Google", "Amazon", can be null.
    appLanguage: String, // e.g., "en", "de", "zh-Hant". Language for compliance views.
    advertisingIdImplementation: AdvertisingIdImplementation, // Implementation of Advertising ID (DISABLED, AUTO, GOOGLE, AMAZON, HUAWEI) based on the store for which you are building. AUTO is the default (best effort for auto-resolving the ADID implementation).
    enableLogs: Boolean, // Enable logging.
    isChinaBuild: Boolean, // Special compliance handling for China builds. Default value is false.
    debug: Boolean, // Enable debug mode for the web bundle.
    eventCallback: ComplianceEventCallback, // Callback for forwarding compliance events.
)

3. Initialize Compliance

Compliance must be initialized at every app start as early as possible. If ComplianceSettings contain publisherProvidedId, updateState will automatically be called, which triggers BE request to fetch latest compliance data:

compliance.initialize(context, complianceSettings)

4. Register a Listener for Updates

Ensure your application receives updates from Compliance by registering a listener:

compliance.addListener(complianceListener)

5. Update Compliance State

Only call this, if publisherProvidedId or homeCountry changes, or if a state refresh is needed for debugging. Start this process by creating a SubjectContext object:

val subjectContext = SubjectContext(
    publisherProvidedId: String? // updated publisher id",
    homeCountry: String? // e.g., "US", "DE". If not provided, Compliance resolves it from the IP.
    debug: Boolean // this will force refresh compliance state
    debugCountry: String? // "US",
    debugRegion: String? // "ca",
)

Then, call:

compliance.updateState(subjectContext)

This triggers backend requests to fetch compliance data, including preference collectors.

6. Collect User Preferences

Once compliance data is ready, the SDK invokes onPreferenceCollectionReady(). At this point, trigger preference collection:

compliance.collectPreferences()

Upon completion, onPreferenceCollected() is called, confirming that preferences have been collected.

7. Check Interest-Based Advertising (IBA) Permission

After collecting preferences, verify whether Interest-Based Advertising (IBA) is allowed:

val isIBAAllowed = compliance.checker.isInterestBasedAdvertisingAllowed(vendorID: String?)

This method returns a Boolean (true or false) based on the user’s preferences.