Support Home > SDK Integration > Consent SDK – Using the SDK

Consent SDK – Using the SDK


The Kochava Consent SDK supports CCPA through the use of IAB’s U.S. Privacy String. An understanding of how the U.S. Privacy String represents consent status is recommended to use this SDK properly.

Take time to review IAB’s U.S. Privacy String spec if necessary.

 

BEST PRACTICES: This documentation is specific to California’s CCPA consent management. For GDPR consent, refer to our Intelligent Consent Manager documentation.

DISCLAIMER: Kochava does not offer legal advice for businesses in relation to CCPA compliance. Information herein is for reference only and businesses are encouraged to seek their own legal counsel regarding CCPA compliance efforts and obligations.

 

Before integrating the SDK, ensure you have set your desired CCPA app settings within the Kochava dashboard. The SDK will not function properly until the following settings have been provided under the CCPA tab:

  1. Whether CCPA applies to only California or all of the United States.
  2. Your app’s correct Package ID, which is the Android package name or iOS bundle ID.

SDK Integration

Requirements:

  • Xcode 11.3.1

 

  1. Add the Module into your Project.
  2. In order to use the KochavaConsent module, first add it to your project. This can be accomplished using Cocoapods or by downloading the module files manually and adding them to your project.

     

    Using Cocoapods —

    Install one of the following Pods
    Version

     

    Direct Download —

    Download the zip file and add the contents to your project.

     

    The Kochava SDK is modular, providing you with the ability to choose which features you want to integrate and use. For a typical Kochava Consent integration, you need only include the Core and Consent modules. Other modules may be added depending on your needs.

    1. Download the zip file for the selected SDK, along with the zip file for the single dependent module KochavaCore (if you have not done so already). For a complete list of all modules available for direct download see iOS / tvOS. It is important to always download current versions of each module which you choose to integrate so that compatibility is ensured.
    2. Extract the contents, and copy the included files into your project’s folder using Finder. You may add these files to your project under a sub-folder named Kochava.
    3. Right-click on your project in Xcode, select Add Files to (project name), and then select the files to add to your project.
    4. If you are working with multiple targets, you will want to ensure that you’ve included each of the included file(s) in the desired targets by selecting each file and reviewing its target membership in the inspector, which appears on the right side in Xcode.
    5. Ensure that the included static libraries (or frameworks) are included in Linked Frameworks and Libraries in your Project (located under the General tab). These will normally have been added at the moment you added the files to your target. If you are using an SDK which is distributed as a framework, you will need to include the frameworks in both the Embedded Binaries as well as Linked Frameworks and Libraries.

     

  3. Import the module’s main header file.
  4. The current module is natively written in Objective-C. You must import the main header file in order to access its symbols. If you’re working in a project which contains Swift code, you must import this file in the Objective-C Bridging Header. For more information, see the Apple page Migrating your Objective-C Code to Swift.:

Requirements:

  • Android API 16
  • Internet Permissions

 

Latest Version:

Release Notes

 

Add the SDK:

Add the Kochava maven repository to your project level build.gradle file.

 

Add the Kochava Consent SDK and all dependencies to your module level build.gradle file. If you have a multiple module project this should be added to your base module. Replace x.y.z with the version obtained from the Download Badge above.


SDK Usage Overview

The typical use of the Kochava Consent SDK is as follows:

 


Identify the User

Before consent can be meaningful, one or more identities must be registered to associate with consent-related activities. An identity can be as granular as an authenticated user or as broad as a device id; it is up to you and how broadly your consent charter applies. If you’re not sure what to use as an identity, we suggest using the Kochava Device ID, which is an identifier unique to the app installation and easily retrieved via the Kochava Tracker’s Get Device ID API call. You might also generate your own unique device identifier on the first launch.

NOTE: If using the Identity Link feature within the Kochava Tracker, these same identity links should be registered as identities for consent as well.

Once you have registered at least one identity, all consent-related audit trails will be associated with the identities you have registered for the duration of the app launch, or until the identity is unregistered. As a best practice, identities should always be registered before any consent-related activities occur. Only identities which were registered at the time will be associated with a consent-related activity.

Identities are not persisted between app launches; you must always register identities before starting the SDK. This is necessary because, for example, the SDK could often be wrong in assuming the same user was logged in after the app was terminated and launched later. For this reason it is up to the developer to ensure the proper identities are registered before starting the SDK.

Once an identity is known, provide the Register Identity API call with a name and value of the identity. This call can be made anytime and must be made at least once before starting the SDK. Additional identities can continue to be registered after starting the SDK. A unique name and value is required to register an identity. The name should accurately represent the type of identity being provided.

NOTE: Identity names and values are limited to 128 characters in length.

 

Example (Register the Kochava Device ID as an Identity):

 

Example (Register a Known User ID as an Identity):

 

Example (Register Multiple User Identities):

 

Example (Register a Kochava Identity Link as an Identity):

At times, you may wish to unregister an identity. This might be necessary if a known user logs out, and can be accomplished any time by calling the Unregister Identity API. Only identities which previously been registered can be unregistered.

 

Example (Unregister an Existing User Identity):

When an existing identity value changes but the name of the value is still the same, you can update the identity value directly by calling the Register Identity API again for that identity (you do not need to Unregister the name first).

 

Example (Update an Existing User Identity):


Start the SDK

Before starting the Kochava Consent SDK or module, at least one identity must be registered. Once one or more identities have been registered, the Start API call can be made. See Identifying the User below for more information on registering an identity. No additional configuration is needed.

 

Example (Start the SDK):


Access the Configuration

The Kochava Consent SDK provides you with the following consent-related configuration properties, which you can leverage to provide the best user experience while ensuring CCPA compliance:

  • Whether or not CCPA applies to this user
  • Custom host configuration values

NOTE: You must wait for configuration callback before accessing any configuration values for the first time.

A handshake is made asynchronously by SDK to determine configuration values. This means that you must wait for this handshake to complete before accessing the configuration. This handshake takes place immediately, but is subject to the device’s network connection.

The SDK will provide you with a callback when configuration is ready to use. If you do not wish to rely on the callback, you can optionally check the Configuration’s IsReady property any time. However, you must wait for the configuration to be ready at least once on the first launch before accessing its properties.

NOTE: The consent configuration handshake is made periodically, in order to maintain an accurate configuration. This means that the callback will continue to fire periodically, whenever the handshake is made again. This can be useful if you wish to check for updated configuration values only when they are possible. As an example, if a user is in California during the first configuration and then leaves California without ever closing the app, the configuration values will eventually update to reflect this.

 

Example (Wire Up the Callback):

 

Example (Handle the Callback):

 

Example (Check the IsReady Flag):

The SDK will inform you when CCPA applies to the current user. Specifically, you do not need to ask whether the user is in California, you simply need to ask the SDK whether CCPA applies to this user, because this is determined using a combination of the user’s IP-based location and your desired CCPA settings within your app’s dashboard. If you have selected that CCPA applies only to users in California, then the SDK will indicate CCPA mode is present only for users in California. If you have selected the entire United States, then the SDK will indicate CCPA is present for users within the United States.

If CCPA applies to the current user, the SDK will indicate this via the IsModePresent API call within the Configuration object. Simply pass in the desired mode to check, which is “ccpa”.

 

Example (Determine if CCPA Applies to this User):

Custom host configuration, when available, can be accessed via the Host API call within the Configuration object or namespace. Custom key/value pairs that you may have provisioned through our dashboard can be accessed here. It is not necessary to access this object unless you have a specific use case.

 

Example (Getting a Custom Value form the Host Configuration Object):


Display the Consent Dialog

If CCPA applies to the user, the consent dialog, which the SDK creates for you, must be made available to the user at some point and can be obtained by calling the RequestDialog() API. It is up to you to decide precisely when a user should be presented with the consent dialog, but typically the consent dialog would be triggered by providing a Privacy button within a user profile or other options menu. Additionally, if CCPA does not apply to this user, we suggest you disable the Privacy button or show an optional message if it is clicked, but you may wish to simply always show the consent dialog even if CCPA does not apply.

 

BEST PRACTICES: The SDK will automatically set the 1st, 2nd, and 3rd digit of the U.S. Privacy String on your behalf when the consent dialog is displayed and the user interacts with it, which means you should never need to set those digits as long as you are requesting and displaying the consent dialog. Use the CoveredByLSPA() API call to set the 4th digit as you see fit.

 

Our example will assume the consent dialog will be displayed when the user clicks a Privacy button.

 

About the RequestDialog API call:

This API call will provide you with a consent dialog which can be displayed to the user. You may display this dialog at any size, but we strongly recommend it be displayed at or near full-screen, as it contains quite a bit of information. The dialog should be requested only at the moment you wish to display it and should not be requested before then. Before requesting the dialog, always ensure that the Configuration is ready by calling the IsReady() API. It is possible if the user is offline that the Configuration may not be ready, in which case you should prepare to show a temporary, alternate dialog or message.

The SDK will handle updating the U.S. Privacy String automatically as the user interacts with it; however, you will need to close the consent dialog when the user indicates they are done. This is accomplished by subscribing to the Completed callback, which will fire when the dialog should be closed.

 


Set the United States Privacy String

CCPA consent support is based on version 1 of IAB’s U.S. Privacy String (USP). This is a 4-character string designed to easily convey all consent-related status information by setting individual characters of this string. As per the IAB spec, this string is stored in the app’s local storage on disk and is available to all entities within the app. The SDK will listen for and report changes to the USP and automatically create the audit trail necessary for CCPA compliance.

See IAB’s spec: US Privacy String

 

SDK-Managed U.S. Privacy String:

The SDK will automatically set the 1st, 2nd, and 3rd digit of the USP on your behalf when the SDK-provided consent dialog is displayed and the user interacts with it. Use the CoveredByLSPA() API call to set the 4th digit as you see fit. If the CoveredByLSPA() API is never used, the SDK will always set the 4th digit to “-“.

Stop here if you prefer the SDK handle the setting of the USP automatically. If you wish to set it yourself, read on.

 

Self-Managed U.S. Privacy String:

If you do not wish for the SDK to set the USP on your behalf, or you wish to set certain values separately, use the SetUSPrivacyString() API call or one of the individual setters shown in the examples below.

NOTE: If the SDK-provided consent dialog is displayed, the SDK may overwrite the 2nd and 3rd digit of the USP automatically. Keep this in mind when setting the USP yourself.

When setting the USP yourself, the USP should be set anytime a consent-related action occurs in the app, so that the last-set USP value accurately represents the current state of consent. These actions include, but are not limited to:

  • The user has left a CCPA region and CCPA no longer applies
  • The user has entered a CCPA region and CCPA now applies
  • The user has been presented with a consent dialogue
  • The user accepts or declines the consent dialogue
  • The Limited Service Provider Agreement status has changed

To set a new USP value, a call to SetUSPrivacyString API is made. Be aware that the value passed in the setter is precisely what the value will be set to; our SDK will not sanitize or format it. To clear or reset the USP value, pass an empty string (“”) as the value.

NOTE: The US Privacy String should always be 4 characters in length, however our SDK will truncate any value which exceeds 128 characters in length, regardless of where the value was set from.

 

Example (Start the SDK and Set a the U.S. Privacy String Value):

The U.S. Privacy String can also be read from disk using a similar call.

 

Example (Start the SDK and Read the Current Value of the U.S. Privacy String):

For more information on setting proper U.S. Privacy String values, as well as IAB’s CCPA Framework, see:
IAB’s CCPA Framework


Creating a Custom Audit Entry

Audit entries are automatically created for you by the SDK when the US Privacy String is updated and when the current consent mode changes.

It is NOT necessary to create your own audit entries under normal circumstances. Rather, you should focus only on updating the US Privacy String as needed and allow the SDK to create a complete audit trail for you. However, should you wish to create your own audit entry, you may call this API. Please consult with your CSM to determine if a new audit entry is needed before doing so.

 

BEST PRACTICES: Audit entries should be short and concise; they should indicate only that a consent-related activity occurred and should not include other data or user PII. Audit entries can only be created after starting the SDK and are limited to 128 characters in length. The SDK will automatically include the current US Privacy String and all current identities within the entry’s metadata.

 

Example (Create a Custom Audit Entry):


Debugging

The SDK can provide logging output for purposes of debugging and error reporting.

 

BEST PRACTICES: Logging should be used only during development and should not be enabled for production builds.

 

Example (Enabling Logging):