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 forsiteId
anddataLang
.- Replace the placeholder
siteId
(e.g.,"YOUR_SITE_ID"
) with your actual TRUENDOsiteId
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.
- Replace the placeholder
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.
5. Handle Consent Strings and Storage
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 inUserDefaults
usingIABTCF_TCString
.acString
: Save inUserDefaults
usingIABTCF_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
andacString
underIABTCF_TCString
andIABTCF_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 (fromconstants.swift
).dataLang
: Your chosen language code (e.g., "en").tdc
: The storedtruendo_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)
andclose()
is essential. - Persistent Storage: Choose secure storage (e.g.,
UserDefaults
, Keychain). - Data Language: Customize
dataLang
inconstants.swift
and/or where you initialize the web view for localization. - Site ID: Replace the placeholder with your TRUENDO
siteId
inconstants.swift
. - Privacy Settings Handling: Use the stored
truendo_cmp
string to adjust app behavior. - IAB TCF Compliance: Storing
tcString
andacString
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.