Mobile Implementation Overview

Ketch's recommended approach to capturing a users consent on a mobile platform is to utilize a platform specific WebView implementation.

Inside the WebView, a bare HTML page is displayed which loads the Ketch Smart Tag, triggers the appearance of the Preference Center with the users current preferences shown, and upon exit generates applicable TCF/CCPA strings.

Ketch Platform configuration

To ensure the Ketch Smart Tag presents the correct behavior, it is recommended to go through the Basic Ketch Implementation Guide.

Once the platform has been initially configured, you'll need to make a few adjustments for a mobile implementation.

Create a new deployment plan by navigating to Experience Server -> Deployment plans and clicking the Create Plan button.
1. Name the plan mobile, select the desired Theme to use, and click Next.
2. For each Jurisdiction,
  - Select No Experience for Consent & Disclosure Experience.
  - Select the desired experience for Preference Experience.
  Click Next.
3. Select a document for each Document Type and click Save & Finish
Create a new property for each platform.
1. Navigate to Experience Server -> Properties.
2. iOS
  1. Click 'Create Property`.
  2. Name the property and code iOS and ios respectively.
  3. Set the Property Type to mobile.
  4. Click Next.
  5. Leave the environment name production and set the pattern to .*.
    6 . Click Next.
  6. Select the appropriate customer type.
  7. Click Next.
  8. Ensure Ketch Managed Cookie is disabled.
  9. Toggle Custom Identity Spaces on.
  10. Set Location to Querystring, Identity Space to idfa, Name to idfa, and Format to String..
  11. Click Save & Finish.
  12. Click Manage Deployment, select the production environment, and the mobile deployment plan.
  13. Click Deploy.
3. Android
  1. Click 'Create Property`.
  2. Name the property and code Android and android respectively.
  3. Set the Property Type to Android.
  4. Click Next.
  5. Leave the environment name production and set the pattern to .*.
    6 . Click Next.
  6. Select the appropriate customer type.
  7. Click Next.
  8. Ensure Ketch Managed Cookie is disabled.
  9. Toggle Custom Identity Spaces on.
  10. Set Location to Querystring, Identity Space to aaid, and Value to aaid.
  11. Click Save & Finish.
  12. Click Manage Deployment, select the production environment, and the mobile deployment plan.
  13. Click Deploy.

Note: Upon creation of the various properties, the corresponding identity spaces will be automatically created.

iOS: idfa - iOS Advertising ID
Android: aaid - Android Advertising ID

Ketch Smart Tag integration bridge

The Ketch Smart Tag contains a built-in integration bridge to relay events and consent preferences from the Ketch Smart Tag to the calling application. To implement the integration bridge create a blank HTML page with only the code below in the HEAD of the page. A sample integration bridge can be found here.

This same file can be used across all platforms as it has the ability to determine the applications platform and use the corresponding communication pattern to relay information back to the calling application with 1 modification. The organization code in the following block should be updated to reflect the organization's code.

var e=document.createElement("script");
e.type="text/javascript";
e.src=`https://global.ketchcdn.com/web/v2/config/<ORGANIZATION_CODE>/${propertyName}/boot.js`;
e.defer=e.async=!0;
document.getElementsByTagName("head")[0].appendChild(e);
window.semaphore=window.semaphore||[];

It is recommended to add the integration bridge HTML page as an asset to each platform and loaded into the WebView from there.

Using the WebView

The WebView will be used a 2 points during the mobile applications lifecycle.

Application startup/launch
When the application launches, the WebView should be loaded, but not made visible to the user. This allows the initial privacy preferences to be set and stored, or updated for the user. An event will be fired back from the WebView containing the users privacy preferences where they should be stored for use throughout the application.
Viewing/Updating Privacy Preferences
A button or action to View/Update the users privacy preferences will trigger the showing of the WebView. When the user is finished updating their preferences and saves/exits the preferences view, two events will be fired back to the application:
1. Notifying a user's preferences have been updates and need to be stored,
2. The Ketch Preferences experience has been closed and it is time to navigate back to the previous screen

Identities

User identifiers will be passed to the WebView as query parameters. The Ketch Smart Tag will pull out these parameters and use them to identify/store user consent preferences within the Ketch Platform.

The identity parameter names should correspond to the same identity space code defined within the Ketch Platform

Storing consent preferences

When the integration bridge returns the user's consent preferences, it is up to the calling application to store this information. It is recommend to store this information in User Defaults for iOS and Shared Preferences for Android, allowing this information to persist across app launches. This approach is modeled in the sample applications sample applications linked at the bottom of the page.

Considerations

App Tracking Transparency (ATT) - Apple provides the ability for users to opt out of tracking through their AppTrackingTransparency framework. This will prevent your application from accessing the user's IDFA, but also means your app is not permitted to track user activity using other information that identifies the user or their device.

Recommendation
In this case, it is recommend to honor the ATT signal on the user's device, but not persisting it back to the Ketch Platform affecting other platforms associated through the Ketch Identity Map.
Updating consent preferences on app relaunch - It is recommend to update a users consent preferences from the Ketch Platform on app relaunch to reflect and honor any changes made to the user's preferences while on another platform, or device. This is made possible by the Ketch Identity Map where a common identifier can be used.

Sample Applications

These sample applications demonstrate how to implement consent capture and retrieval using the Ketch Smart Tag displayed in a WebView. These applications use the recommended approaches described above.