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

Requirements:

  • Android API 16
  • Internet Permission

 

Add the SDK:

(Release Notes)

 

  1. Add the Maven Central repository to your project level build.gradle file.
  2.  

  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.
  4.  


iOS SDK Integration

  •  

    How to Add a Swift Package:

    If this is your first time adding a Swift Package, follow these steps for each of the modules above you wish to add:

    1. Copy the URL of the swift package to your pasteboard.
    2. In Xcode 12.2 or higher, go to File > Swift Packages > Add Package Dependency.
    3. Paste in the URL of the swift package into the prompt.
    4. Configure the version to the desired major version. Currently you should use

  • Module XCFramework
    KochavaCore
    Core SDK functionality.
    KochavaEntitlements
    Consent management.

     

    How to Add an XCFramework:

    Follow these steps for each of the modules above you wish to add:

    1. Download the XCFramework from the link above and add it to your project.
    2.  

      Expand for Details

      1. Download the release archive containing the XCFramework.
      2. Open the archive and copy the XCFramework into your Xcode project folder using Finder. You will typically want to add this file to the Frameworks folder of your project.
      3. Right click on your project in Xcode, select “Add Files to (project name)”, and add the included file to your project.
      4. If you are working with multiple targets, you will want to ensure that you have included the XCFramework in each of the desired targets by selecting the file and reviewing its target membership in the inspector, which appears on the right side in Xcode.
      5. Ensure that the XCFramework is included in Frameworks, Libraries, and Embedded Content in your project target (located under the General tab). It will normally have been added at the moment you added the file to your target.

       

    3. Import the XCFramework.

     

    Sample Code:

    XCFramework(s), Swift —

     

    XCFramework(s), Objective-C —

  • Module iOS Static Library tvOS Static Library
    KochavaCore
    Core SDK functionality.
    KochavaEntitlements
    Consent management.

     

    How to Add a Static Library:

    Follow these steps for each of the modules above you wish to add:

    1. Download the static library from the link above and add it to your project. We recommend integrating XCFrameworks rather than static libraries.
    2.  

      Expand for Details

      1. Download the release archive containing the static library.
      2. Open the archive and copy the static library (including the folder wrapping it with the headers) into your Xcode project folder using Finder. You will typically want to add this to the root folder of your project, and we recommend placing it under a sub-folder named Kochava.
      3. Right click on your project in Xcode, select “Add Files to (project name)”, and the included files to your project.
      4. If you are working with multiple targets, you will want to ensure that you have included the static library in each of the desired targets by selecting associated files and reviewing their target membership in the inspector, which appears on the right side in Xcode.
      5. Ensure that the included static library is included in Frameworks, Libraries, and Embedded Content in your project target (located under the General tab). It will normally have been added at the moment you added the file to your target.

       

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

      Sample Code:

      Static Library(s), Objective-C —


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:


     

    Debugging:

    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: