iOS Implementation

Introduction

Overview

InMobiChoice empowers site owners to efficiently handle consent across diverse devices and environments, including iOS. The InMobiChoice Mobile CMP (CMP) strictly adheres to the IAB TCF v2 standard.

System Requirements

Ensure a minimum iOS version of 11.0 or above for seamless operation.

User Interface (UI)

The CMP's User Experience (UX) is seamlessly integrated within a viewController, presenting a user-friendly overlay on top of the rootViewController of your application.

Data Management

The IAB TCF v2 mobile specifications securely store all consent data, utilizing UserDefaults for robust data management.

UI customisation

We have UI customization capabilities with our Choice mobile SDK. This feature empowers developers to tailor color schemes and font styles for all UI components used in the Choice Mobile CMP. This ensures seamless integration with the host application's UI style. For more information on customizing styles, see UI Customization for Mobile iOS.

CMP SDK & Configuration

Configure InMobi Choice for Your Mobile App

Before integrating InMobi Choice into your mobile app must be configured on the dashboard. Follow these steps:

1. Log in to the Choice dashboard using your credentials.
2. Click the Protect An App button.

Create New App

1. Navigate to the Create a New App page.
2. Provide essential details about your app, including its name, type, logo, and the consent you aim to acquire from users.
3. After completion, click the Download SDK button.

Set up Xcode Project

From Downloaded Zip

1. From your open XCode project, select the top (blue) project file from the left file pane.

   

2. On the General tab, find the Frameworks, Libraries, and Embedded Content section and click the "+" button.
3. On the bottom left of the popover, click the Add Other… dropdown, select Add Files…, and select ChoiceMobile.framework file.

   

4. Follow the instructions to configure the simulator to ignore arm64 (Xcode 13+):
   1. In Xcode Targets settings, navigate to Build Settings using the top tabs.
   2. Select All and locate the Exclude Architectures option.
   3. Add a new section to the Debug row. The default value will be Any SDK, which should be modified to Any iOS Simulator SDK.
   4. In the right column, enter arm64.

      

Integrate Choice for Mobile Apps

The following methods are supported for integrating Choice:

• SDK Integration through Swift
• SDK Integration through SwiftUI
• SDK Integration through Objective-C

SDK Integration (Swift)

1. In your UIApplicationDelegate class, import ChoiceMobile using the following statement.

   import ChoiceMobile
   	

2. Initialize Choice: Call ChoiceCmp.shared.startChoice method. This method requires the following parameters:

   • pcode: A unique identifier retrievable from the web portal. For more information, see Find Your P-CODE.
   • delegate: Assign a delegate to receive callbacks.
   • ccpaDelegate (Optional): Assign a CCPA delegate to receive CCPA callbacks.
   • shouldDisplayIDFA (Optional): Set the value to true if you want to display the tracking permission popup.

   Note

   If you set shouldDisplayIDFA parameter to true, it is imperative to add the NSUserTrackingUsageDescription key to your info.plist. Provide a clear description of how your app will utilize this value.

import UIKit 
import ChoiceMobile   

@main 
class AppDelegate: UIResponder, UIApplicationDelegate, ChoiceCmpDelegate, CCPADelegate { 
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { 
        ChoiceCmp.shared.startChoice(pcode: "<YOUR PCODE>", delegate: self) 
        return true 
    } 
}

3. To utilize the functionality, ensure you implement the necessary callbacks. For detailed best practices on callbacks, refer to the next section.

   func didReceiveIABVendorConsent(tcData: TCData, updated:Bool) {  } 
   func didRecieveNonIABVendorConsent(nonIabData: NonIABData, updated:Bool) {  } 
   func didReceiveAdditionalConsent(acData: ACData, updated:Bool) {} 
   func didReceiveCCPAConsent(string: String) { } 
   func cmpDidError(error: Error) { }
   	

4. It's important to implement a mechanism that allows users to manually trigger the CMP dialog, enabling them to modify their consent preferences at any time. Typically, this feature can be incorporated into a menu, placed alongside your app's privacy policy or other settings.

   Note

   While the startChoice method is designed to display the popup when necessary, and this additional method is specifically used for the on-demand showing of the CMP dialog:

   To open the CMP, call:

   ChoiceCmp.shared.forceDisplayUI()
   

SDK Integration (SwiftUI)

1. Import ChoiceMobile in your App class.

   import ChoiceMobile
   	

2. Initialize Choice: Call the method ChoiceCmp.shared.startChoice within the active state of the onChange notification of the main WindowGroup. This method anticipates the following:

   Note

   If you set shouldDisplayIDFA parameter to true, it is imperative to add the NSUserTrackingUsageDescription key to your info.plist. Provide a clear description of how your app will utilize this value.

   import SwiftUI 
   import ChoiceMobile  
   
   @main 
   struct ChoiceSwiftUIApp: App { 
       @Environment(\.scenePhase) private var scenePhase     
       var body: some Scene {          
           WindowGroup { 
               ContentView() 
           }.onChange(of: scenePhase) { newScenePhase in 
               if newScenePhase == .active {  
   ChoiceCmp.shared.startChoice(pcode: "< YOUR PCODE >", delegate: ChoiceDelegate()) 
               } 
           } 
       } 
   }
   

   • pcode: A unique identifier retrievable from the web portal. For more information, see Find Your P-CODE.
   • delegate: Assign a delegate to receive callbacks.
   • ccpaDelegate (Optional): Assign a CCPA delegate to receive CCPA callbacks.
   • shouldDisplayIDFA (Optional): Set the value to true if you want to display the tracking permission popup.
3. To implement the Choice SDK delegates, follow the instructions:
   1. Create a delegate class that conforms to the ChoiceCmpDelegate protocol.
   2. Implement the required callbacks specified by the protocol.

   import SwiftUI 
   import ChoiceMobile 
   
   @main 
   struct ChoiceSwiftUIApp: App { 
       @Environment(\.scenePhase) private var scenePhase 
       var delegate = ChoiceDelegate()      
       var body: some Scene {          
           WindowGroup { 
               ContentView() 
           }.onChange(of: scenePhase) { newScenePhase in 
               if newScenePhase == .active { ChoiceCmp.shared.startChoice(pcode: "< YOUR PCODE >", delegate: delegate) 
               } 
           } 
       } 
   }  
   class ChoiceDelegate: NSObject, ChoiceCmpDelegate, CCPADelegate { 
       func cmpDidLoad(info: ChoiceMobile.PingResponse) {          
       }      
       func cmpDidShow(info: ChoiceMobile.PingResponse) {          
       }      
       func didReceiveIABVendorConsent(tcData: ChoiceMobile.TCData, updated: Bool) { 
           //Use TCData to know the consent information related to IAB vendors 
       }      
       func didReceiveNonIABVendorConsent(nonIabData: ChoiceMobile.NonIABData, updated: Bool) { 
           //Use NonIABData to know the consent information related to Non-IAB vendors 
       }      
       func didReceiveAdditionalConsent(acData: ChoiceMobile.ACData, updated: Bool) { 
           //Use ACData to know the consent information related to Google vendors 
       }      
       func cmpDidError(error: Error) {          
       }      
       func didReceiveCCPAConsent(string: String) {          
       }           
   }
   

   Note

   The ChoiceCmp maintains a weak reference to the delegate object to prevent retain cycles. Ensure that you retain a reference to the delegate in your code to prevent it from being deallocated.

4. If you set shouldDisplayIDFA parameter to true, it's recommended to include NSUserTrackingUsageDescription in your info.plist file. This communicates to users that your app requests their consent for tracking.
5. Implementing a feature enabling users to trigger the CMP dialog manually is essential. This allows users to modify their consent preferences whenever they choose. Typically, this functionality can be incorporated into a menu alongside your app's privacy policy or other settings. To open the CMP, call:

   ChoiceCmp.shared.forceDisplayUI()
   

   Note

   The startChoice method displays the popup automatically if necessary. The additional method is specifically designed for on-demand popup display.

SDK Integration (Objective-C)

For products utilizing React Native, it's worth noting that the Choice CMP is fully compatible with Objective-C. Follow the instructions to outline the requirements for integrating the Choice CMP with React Native:

1. Import ChoiceMobile into your UIApplicationDelegate header file (.h):

#import <ChoiceMobile/ChoiceMobile.h>

2. Make your delegate class conform to the ChoiceCmpDelegate protocol, or create a separate delegate class.

@interface AppDelegate : UIResponder <UIApplicationDelegate, ChoiceCmpDelegate, CCPADelegate>

3. Implement the required callbacks.

   - (void)cmpDidErrorWithError:(NSError * _Nonnull)error {}
   - (void)cmpDidLoadWithInfo:(PingResponse * _Nonnull)info {}
   - (void)cmpDidShowWithInfo:(PingResponse * _Nonnull)info {}
   - (void)didReceiveAdditionalConsentWithAcData:(ACData * _Nonnull)acData updated:(BOOL)updated {}
   - (void)didReceiveIABVendorConsentWithTcData:(TCData * _Nonnull)tcData updated:(BOOL)updated {}
   - (void)didReceiveNonIABVendorConsentWithNonIabData:(NonIABData * _Nonnull)nonIabData updated:(BOOL)updated {}
   - (void)didReceiveCCPAConsent:(NSString * _Nonnull)string { }
   	

4. In your UIApplicationn delegate's application:didFinishLaunchingWithOptions: method, insert the following code below any rootViewController initialization:

   [[ChoiceCmp shared] startChoiceWithPcode:@"< YOUR PCODE >" delegate: self ccpaDelegate: self shouldDisplayIDFA:false];
   	

5. If you've set shouldDisplayIDFA parameter to true, you should include the NSUserTrackingUsageDescription in your info.plist file. This communicates to users that your app requests their consent for tracking.
6. Implementing a mechanism that enables users to trigger the CMP dialog manually is essential. This empowers users to modify their consent preferences whenever they desire. Typically, this functionality can be integrated into a menu alongside your app's privacy policy or other settings. The startChoice method displays the popup automatically if necessary. This additional method is only required for on-demand popup display. To open the CMP, call::

   ChoiceCmp.forceDisplayUI()
   

   At this stage, you have successfully integrated the SDK. The SDK will actively monitor lifecycle events to ensure that consent is consistently available. If, at any point, consent is not found, the CMP will promptly appear to request the user's consent. Each time a user is prompted, the associated callbacks will be triggered.

Implement Delegate

implement all three consent callbacks, even if you haven't configured all the consent features. This ensures comprehensive consent handling and minimizes the risk of overlooking any crucial aspects.

1. Manage IAB Vendor Compliant Consent: The didReceiveIABVendorConsent callback is triggered upon obtaining user consent for IAB-compliant vendors. You can find a list of IAB-compliant vendors here. Ideally, IAB-compliant mobile frameworks will autonomously incorporate this consent and adjust their configuration accordingly. However, it's worth noting that not all frameworks are IAB-compliant. If you're uncertain, it's advisable to contact your vendor for clarification. In cases where the framework is not compliant, you'll be responsible for handling the consent process yourself. If the framework prescribes a setup method typically called in didFinishLaunchingWithOptions, ensure it is relocated here and executed after verifying the consent. For instance:

   func didReceiveIABVendorConsent(tcData: TCData, updated: Bool) {
       // Use TCData to know the consent information related to IAB vendors
       
       // Use gdprApplies to check if the gdpr applies or not
       print(tcData.gdprApplies)
       
       // Use tcData.vendor.consents to checkout the vendor consents
       print(tcData.vendor.consents)
   }
   

   TCString can also be accessed directly from the UserDefaults using the key IABTCF_TCString.

2. Manage Non-IAB Vendor Consent: The didRecieveNonIABVendorConsent callback pertains to vendors configured in the Choice Portal and do not automatically validate consent. Here, consent is provided straightforwardly: either a blanket, yes or no. To verify consent, locate the specific vendor by their assigned ID in the Choice Portal using the following method:

   func didReceiveNonIABVendorConsent(nonIabData: NonIABData, updated: Bool) {
       //Use NonIABData to know the consent information related to Non-IAB vendors
       
       // Use gdprApplies to check if the gdpr applies or not
       print(nonIabData.gdprApplies)
       
       // Use nonIabData.nonIabVendorConsents to checkout the vendor consents
       print(nonIabData.nonIabVendorConsents)
       
   }
   	

3. Manage Google Vendor Consent: Another crucial callback to be mindful of is didReceiveAdditionalConsent. This callback is specifically invoked if you have enabled Google Vendors in the portal. For more information, see GDPR overview and guidance. As with the other callbacks, utilize this callback to handle consent for Google Vendors effectively.

   func didReceiveAdditionalConsent(acData: ACData, updated: Bool) {
       //Use ACData to know the consent information related to Google vendors
       
       // Use gdprApplies to check if the gdpr applies or not
       print(acData.gdprApplies)
       
       // Use acData.additionalVendorConsent to checkout the vendor consents
       print(acData.additionalVendorConsent)
       
    }
   

   While likely not essential for typical usage, additional callbacks are available for debugging or advanced scenarios. One such callback is cmpDidError, which triggers whenever the CMP exits unexpectedly and fails to collect consent.

CCPA Integration

Display CCPA Screen

After successfully initializing the SDK, you can present the CCPA screen by invoking the following method:

[[ChoiceCmp shared] startCCPAWithPcode:@"<YOUR PCODE>" ccpaDelegate:self];

ChoiceCmp.shared.startCCPA(pcode: "<YOUR PCODE>", ccpaDelegate: self)

Receive CCPA Consent String

To receive a callback for the CCPA consent string once the user taps the confirm button, implement the CCPADelegate protocol. You can access the obtained string through UserDefaults using the key IABUSPrivacy_String.

- (void)didReceiveCCPAConsentWithString:(NSString *)string {
    // Use the string for CCPA consent
}

func didReceiveCCPAConsent(string: String) {
    // Use the string for CCPA consent
}

Find Your P-CODE

To initialize the SDK, you must provide your account's p-code for proper identification. After you log in to the Choice portal, you can see the p-code at the top right corner of the screen.

Displaying IDFA Popup

The CMP provides an option to seamlessly integrate the new native IDFA permission popup (ATTrackingManager), provided the user has been granted permission for the CMP purposes. Presenting the popup right after the CMP offers users more context about the request, potentially leading to higher acceptance rates.

The popup will be triggered if GDPR applies and consent has been obtained, or if GDPR is explicitly stated not to apply.

If your app and associated vendors will never utilize the IDFA, or if you intend to display this popup at a different time, set this option to false.

However, if you choose to set this option to true, ensure you provide a usage description in your Info.plist. To do this, add a new key named NSUserTrackingUsageDescription and furnish it with a concise yet comprehensive description of how the IDFA will be utilized. For instance, "We use this value to help serve you relevant advertising".