iOS | TRUENDO Documentation

TRUENDO CMP Integration Guide for iOS

This guide provides step-by-step instructions to integrate the TRUENDO Consent Management Platform (CMP) into your iOS application using the provided Swift library. It includes details on how to handle and store consent strings (truendo_cmp, tcString, acString) in compliance with IAB TCF standards and Google's requirements.

Introduction#

The TRUENDO CMP library allows you to integrate a consent management platform into your iOS application. This enables you to display a consent banner to users and manage their privacy settings in compliance with data protection regulations, including the IAB Transparency and Consent Framework (TCF).

Prerequisites#

Xcode installed on your Mac.
The TRUENDO iOS demo app.
A TRUENDO siteId provided by TRUENDO.

Downloading the Library#

Obtain the necessary files here:

libTruendo.a (static library)
Resources.bundle (contains required resources)
Truendo.swiftmodule (Swift module interface)

Select the appropriate files for your project based on the target (device or simulator).

Adding the Library to Your Xcode Project#

1. Add Files to Project

Drag and Drop Method:

Open your Xcode project.
Drag libTruendo.a, Resources.bundle, and the Truendo.swiftmodule folder into your project's file navigator.
In the dialog that appears, ensure:
- "Copy items if needed" is checked.
- Your app target is selected under Add to targets.

2. Link the Library

Using General Settings:

Select your project in the Project Navigator.
Choose your app target.
Go to the General tab.
Scroll to Frameworks, Libraries, and Embedded Content.
Click the + button.
Click Add Other... and select Add Files....
Navigate to libTruendo.a, select it, and click Open.

Alternatively, Using Build Phases:

Select your app target.
Go to Build Phases.
Expand Link Binary With Libraries.
Click the + button.
Click Add Other... and select Add Files....
Navigate to libTruendo.a, select it, and click Open.

Configuring Build Settings#

1. Add Library Search Paths

Select your app target.
Go to Build Settings.
Ensure All and Combined are selected to view all settings.
Search for Library Search Paths.
Double-click the field and add the path to the directory containing libTruendo.a. For example:

$(PROJECT_DIR)/path/to/libTruendo.a
Repeat for all configurations (Debug, Release).

2. Add Swift Import Paths

In Build Settings, search for Import Paths under Swift Compiler - Search Paths.
Double-click the field and add the path to the directory containing Truendo.swiftmodule. For example:

$(PROJECT_DIR)/path/to/Truendo.swiftmodule
Ensure the path is added for all configurations.

Implementing the TRUENDO CMP in the Demo App#

1. Import the TRUENDO Module

In your Swift files where you plan to use the TRUENDO CMP, import the module:


import Truendo

2. Implement the Delegate

Your class needs to conform to the TruendoWebViewDelegate protocol to receive updates:


class ViewController: UIViewController, TruendoWebViewDelegate {
    // Implement delegate methods
}

Delegate Methods:

updatedCookie(with body: String): Called when the consent strings are updated. Use this method to store the updated settings.
close(): Called when the TRUENDO web view should be closed (e.g., when the user dismisses the consent banner).

3. Initialize and Display the TRUENDO WebView


class ViewController: UIViewController, TruendoWebViewDelegate {
    var webView: TruendoWebView!

    override func viewDidLoad() {
        super.viewDidLoad()
        webView = TruendoWebView(frame: view.bounds, delegate: self)
        view.addSubview(webView)

        // Proceed to display the consent banner or privacy settings panel
    }
}

4. Adding Your Unique TRUENDO Site ID and Setting the Language

In the Demo Project:

Open TruendoTest.xcodeproj in Xcode.
In the Xcode Project Navigator, select constants.swift.
Inside constants.swift, you will find variables for siteId and dataLang.
- Replace the placeholder siteId (e.g., "YOUR_SITE_ID") with your actual TRUENDO siteId provided by TRUENDO.
- The dataLang parameter controls the default language of the consent banner. For example, if the default is set to "de" for German, you can change it to "en" for English.

Example:


let siteId = "YOUR_ACTUAL_TRUENDO_SITE_ID"
let dataLang = "en" // Change this to your preferred language code

These changes ensure that the consent banner and preferences displayed will correspond to your specific configuration and chosen language.

a. Understanding the Consent Strings

When the user interacts with the consent banner, you will receive a JSON-formatted string in the updatedCookie(with body: String) delegate method. This string contains three key consent strings:

truendo_cmp: TRUENDO's own consent string containing user consent preferences.
tcString: The IAB TCF Transparency and Consent (TC) string.
acString: The Additional Consent (AC) string for non-IAB vendors.

Example body:


{
  "truendo_cmp": {
    "ack": true,
    "exp": "2024-10-18T10:00:00Z",
    "necessary": true,
    "preferences": false,
    "marketing": true,
    "statistics": false,
    "social_content": false,
    "add_features": false,
    "prodirversion": 1,
    "user_id": "unique-user-id"
  },
  "tcString": "COtybnwOtybnwABABBENAt-AAAAMeAAAKAB8wAQABAAdgAIDqALGA",
  "acString": "1~7.12.35.62.66.70.89.93.126"
}

b. Saving Consent Strings

You need to extract these strings and store them:

truendo_cmp: Store securely (e.g., UserDefaults, Keychain).
tcString: Save in UserDefaults using IABTCF_TCString.
acString: Save in UserDefaults using IABTCF_AddtlConsent.

Example Code:


func updatedCookie(with body: String) {
    guard let data = body.data(using: .utf8) else { return }
    do {
        let consentData = try JSONDecoder().decode(TruendoDataContainer.self, from: data)

        let truendoCMPData = try JSONEncoder().encode(consentData.truendo_cmp)
        let truendoCMPString = String(data: truendoCMPData, encoding: .utf8)
        saveTruendoCMPString(truendoCMPString)

        UserDefaults.standard.set(consentData.tcString, forKey: "IABTCF_TCString")
        UserDefaults.standard.set(consentData.acString, forKey: "IABTCF_AddtlConsent")

        UserDefaults.standard.set(1, forKey: "IABTCF_EnableAdvertiserConsentMode")

    } catch {
        print("Failed to decode consent data: (error)")
    }
}

Functions to Save and Retrieve truendo_cmp:


func saveTruendoCMPString(_ cmpString: String?) {
    guard let cmpString = cmpString else { return }
    UserDefaults.standard.set(cmpString, forKey: "TruendoCMPString")
}

func retrieveTruendoCMPString() -> String? {
    return UserDefaults.standard.string(forKey: "TruendoCMPString")
}

c. Implementing IAB TCF Compliance

To comply with IAB TCF and Google:

Save tcString and acString under IABTCF_TCString and IABTCF_AddtlConsent.
Enable advertiser consent mode:


UserDefaults.standard.set(1, forKey: "IABTCF_EnableAdvertiserConsentMode")

6. Check for Updates

Use isUpdateNeeded to determine if consent needs updating:


webView.isUpdateNeeded(siteId: siteId, tdc: storedTruendoCMPString ?? "") { [weak self] isNeeded in
    DispatchQueue.main.async {
        if isNeeded {
            self?.webView.show(with: siteId, dataLang: dataLang, tdc: nil)
        } else {
            self?.webView.show(with: siteId, dataLang: dataLang, tdc: storedTruendoCMPString)
        }
    }
}

Parameters:

siteId: Your TRUENDO site ID (from constants.swift).
dataLang: Your chosen language code (e.g., "en").
tdc: The stored truendo_cmp string.

Example Implementation:


import UIKit
import Truendo

class ViewController: UIViewController, TruendoWebViewDelegate {
    var webView: TruendoWebView!
    let siteId = "YOUR_ACTUAL_TRUENDO_SITE_ID"  // Make sure this matches constants.swift
    let dataLang = "en" // Also ensure consistency with constants.swift

    override func viewDidLoad() {
        super.viewDidLoad()
        webView = TruendoWebView(frame: view.bounds, delegate: self)
        view.addSubview(webView)

        let storedTruendoCMPString = retrieveTruendoCMPString()

        webView.isUpdateNeeded(siteId: siteId, tdc: storedTruendoCMPString ?? "") { [weak self] isNeeded in
            DispatchQueue.main.async {
                if isNeeded || storedTruendoCMPString == nil {
                    self?.webView.show(with: self?.siteId ?? "", dataLang: self?.dataLang ?? "en", tdc: nil)
                } else {
                    self?.webView.show(with: self?.siteId ?? "", dataLang: self?.dataLang ?? "en", tdc: storedTruendoCMPString)
                }
            }
        }
    }

    // MARK: - TruendoWebViewDelegate

    func updatedCookie(with body: String) {
        guard let data = body.data(using: .utf8) else { return }
        do {
            let consentData = try JSONDecoder().decode(TruendoDataContainer.self, from: data)
            let truendoCMPData = try JSONEncoder().encode(consentData.truendo_cmp)
            let truendoCMPString = String(data: truendoCMPData, encoding: .utf8)
            saveTruendoCMPString(truendoCMPString)

            UserDefaults.standard.set(consentData.tcString, forKey: "IABTCF_TCString")
            UserDefaults.standard.set(consentData.acString, forKey: "IABTCF_AddtlConsent")
            UserDefaults.standard.set(1, forKey: "IABTCFEnableAdvertiserConsentMode")

        } catch {
            print("Failed to decode consent data: (error)")
        }
    }

    func close() {
        webView.removeFromSuperview()
        webView = nil
    }

    // MARK: - Consent Strings Storage

    func saveTruendoCMPString( cmpString: String?) {
        guard let cmpString = cmpString else { return }
        UserDefaults.standard.set(cmpString, forKey: "TruendoCMPString")
    }

    func retrieveTruendoCMPString() -> String? {
        return UserDefaults.standard.string(forKey: "TruendoCMPString")
    }
}

// MARK: - Consent Data Models

struct TruendoCookie: Codable {
    let ack: Bool
    let exp: String
    let necessary: Bool
    let preferences: Bool
    let marketing: Bool
    let statistics: Bool
    let social_content: Bool
    let add_features: Bool
    let prodirversion: Int
    let user_id: String
}

struct TruendoDataContainer: Codable {
    let truendo_cmp: TruendoCookie
    let tcString: String
    let acString: String
}

Additional Notes#

Delegate Methods Are Required: Implementing updatedCookie(with body: String) and close() is essential.
Persistent Storage: Choose secure storage (e.g., UserDefaults, Keychain).
Data Language: Customize dataLang in constants.swift and/or where you initialize the web view for localization.
Site ID: Replace the placeholder with your TRUENDO siteId in constants.swift.
Privacy Settings Handling: Use the stored truendo_cmp string to adjust app behavior.
IAB TCF Compliance: Storing tcString and acString with IAB keys ensures interoperability.
Google Advertiser Consent Mode: Use the IABTCF_EnableAdvertiserConsentMode flag.

Conclusion#

By following this guide and customizing the siteId and dataLang values in constants.swift, you can easily adapt the TRUENDO CMP demo to reflect your unique configuration. Proper handling and storage of consent strings ensure compliance with data protection regulations and seamless integration with third-party SDKs and services.

For any issues or support, please contact TRUENDO's support team.

Note: This guide assumes basic familiarity with Xcode and Swift. Adjust file paths and variable names according to your project's structure.

Start typing to search, or search using the advanced options below.

Sources: