Support Home > SDK Integration > Entitlements – Using the SDK

Entitlements – Using the SDK

The Kochava Entitlements SDK empowers Kochava for Subscription Media tracking services. The following document describes the Android and iOS SDK integration as well as an outline of the typical use of the Kochava Entitlements SDK.

Android SDK Integration


  • Android API 16
  • Internet Permission


Add the SDK:

(Release Notes)


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

  3. Add the Kochava Entitlements SDK and its 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 link above.

iOS SDK Integration

  1. If desired, you may optionally retrieve the latest version from Bintray here.
  2. The three packages specifically being referenced are:

Modules KochavaEntitlements and KochavaTracker each have module KochavaCore as a dependency, and therefore a compatible version of each must be used together. This means if you are already using a different version of module KochavaTracker you will need to update to the version provided with module KochavaEntitlements.


Using the Downloaded Zip Files:

  1. Extract the contents of the Entitlements and Tracker module zip archives, and copy the included files into your project’s folder using Finder. You will typically want to add these files to the root folder of your project.
  2. Right-clicking on your project in Xcode, select “Add Files to (project name)” and the included files to your project.
  3. If you are working with multiple targets, you will want to ensure that you have 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.
  4. Ensure that the included static library (or framework) is included in Linked Frameworks and Libraries in your Project target(s). It will normally have been added at the moment you added the file to your target.


Import the Module’s Main Header File:

The current Apple SDK is natively written in Objective-C. You must import the main header file in order to access its symbols. If you’re using static libraries and 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.:


Sample Code —

SDK Usage

After integration, typical use of the Kochava Entitlements SDK is as follows:

  1. Identify the User.
  2. One or more identities must be registered to associate with receipts which are sent from the SDK.

    An identity may be any unique key-value pair which identifies the current user. Identities should transcend platforms and devices; a proper identity should be the same for a single user across any platform, whether it be mobile, web, or desktop. An example of this would be a user-specific identifier such as a hashed user id or email.

    While a device id can be used for an identity, a device id is not something you can easily associate to users across multiple platforms and does not accurately reflect the user on a device which is shared within a household. If you choose to include a device id as an identity, be sure to register a user-specific identifier in addition, so that the user can be tied to the device id.

    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’s up to the developer to ensure the proper identities are registered before starting the SDK.

    NOTE: If using the Identity Link feature within the Kochava Tracker SDK, these same Identity Links values should be registered as identities with the Entitlements SDK as well.


    Register an Identity:

    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 key names are unique. Registering a new identity under an existing key will overwrite the existing key and value.

    NOTE: Identity names and values are limited to 128 characters in length. It is strongly recommended for the user’s primary key value pair to be named user. If you have access to their email address, it should be labeled as hem.


    Example Register a Known User ID and Email Hash as an Identity:


    Example Update User Identities:


    Example Register a Kochava Identity Link as an Identity:


    Unregister 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 providing the identity key name to the Unregister Identity API. Only identities which have previously been registered can be unregistered.


    Example Unregister an Existing User Identity:

  3. Start the SDK.
  4. Before starting the Kochava Entitlement SDK, at least one identity must be registered as is described in the previous section. Once one or more identities have been registered, the Start API call can be made. No additional configuration is needed.


    Example Start the SDK:

  5. Report Purchases to the SDK.
  6. Any time a purchase of any kind is completed, the SDK must be notified of the purchase. For Android, this also requires passing the receipt-related data to the SDK, while iOS will read the updated receipt automatically.

    NOTE: Always make sure your identities are up to date. When you report a purchase, that purchase will be associated with the current identities registered within the SDK.


    Example Inform the SDK of a Purchase:



    Logging output may be provided for purposes of debugging and error reporting. Logging should be used only during development and should not be enabled for production builds.


    Example Enable Logging: