Purchase Tracking

Segmenting your users by their spending activity is one of the Tapjoy SDK ‘s most powerful features. For example, you might want to show advertisements to your non-spending users, but show In App Purchase promotions to your "whale" users. In order to use this feature, you must let Tapjoy know about the spending activity of your users. You do this with the Tapjoy.trackPurchase call. You should track every purchase the user makes in your application, regardless of whether this purchase was made via your in-app store or via some other mechanism, such as a Tapjoy IAP promotion.

In order for Purchase Tracking with receipt validation to work on Android, you must enter your application’s License Key into Settings > Analytics > Receipt Validation.

You can find out how to get your application’s License Key from the Licensing section of the Google Services Documentation.

The following call is used to track purchases with receipt validation:

  Tapjoy.trackPurchase(skuDetails, purchaseData, dataSignature, campaignID);

1. Explanation of Parameters

1. skuDetails – a String in JSON Object format that contains product item details (according to the Specification on Google Play)
2. purchaseData – a String in JSON format that contains details about the purchase order. It is returned by the operating system after you make the purchase call. Use null to not use validation.
3. dataSignature – String containing the signature of the purchase data that the developer signed with their private key. It is returned by the operating system after you make the purchase call. Use null to not use validation.
4. campaignId – the campaign id of the PurchaseRequest if it initiated this purchase. This can be null if you don’t wish to track which campaign initiated this purchase.

The following is an example of IAP tracking. For IAP tracking with receipt verification, you should only track purchases that have receipt data.

The currency codes used follow the ISO 4217 standard.

Once purchase tracking is implemented, you will be able to see charts in the "IAP Revenue" section of the dashboard.

2. Referrer

A. Integrate Tapjoy's InstallReferrer client with Tapjoy Analytics

1. Add com.android.installreferrer:installreferrer dependency in build.gradle <app_level>
2. Call Tapjoy.activateInstallReferrerClient(context); in the onCreate() method of the launcher Activity in your application.

B. Implement your own InstallReferrer client and use Tapjoy Analytics

1. Create a class which implements InstallReferrerStateListener in your app project
2. Add "com.android.installreferrer:installreferrer” dependency in build.gradle <app_level>
3. From onInstallReferrerSetupFinished callback of the class:
   1. Get referrer value from getInstallReferrer() method of ReferrerDetails from ReferrerClient object.
   2. call Tapjoy.setInstallReferrer(context, referrer); by passing the context and the referrer value just retrieved. This method must be called only once by app install.

Sample Implementation

public class EasyAppInstallReferrer implements InstallReferrerStateListener {

   private Context referrerContext;
   private InstallReferrerClient mReferrerClient;
   private String TAG = "Tapjoy Install Referrer";
   private SharedPreferences prefs;

   public void init(Context context) {
       try {
             mReferrerClient = InstallReferrerClient.newBuilder(context).build();
       } catch (Exception e) {
         Log.w(TAG, e.getMessage());
       }
     /*
     * Notes from google documentaiton: Unless the app is reinstalled, the install referrer information will be available for 90 days
     * To avoid unnecessary API calls in your app, you should invoke the API only once during the first execution after install.
     */
     prefs = context.getSharedPreferences("TapjoyEasyAppReferrer", Context.MODE_PRIVATE);
     if(!prefs.getBoolean("didSetUpTapjoyInstallReferrer", false)) {
       mReferrerClient.startConnection(this);
     }
     referrerContext = context;
   }

   @Override
   public void onInstallReferrerSetupFinished(int responseCode) {
     switch (responseCode) {
       case InstallReferrerClient.InstallReferrerResponse.OK:
         try {
           getReferrer();
           mReferrerClient.endConnection();
         } catch (RemoteException e) {
           TapjoyLog.e(TAG, e.getMessage());
         } catch (Exception e) {
           TapjoyLog.e(TAG, e.getMessage());
         }
         break;
       case InstallReferrerClient.InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
         // API not available on the current Play Store app.
         break;
       case InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE:
         // Connection couldn't be established.
         break;
     }

   }

   @Override
   public void onInstallReferrerServiceDisconnected() {
     // Try to restart the connection on the next request to
     // Google Play by calling the startConnection() method.
     if (referrerContext != null) {
       init(referrerContext);
     }
   }

   private void getReferrer() throws RemoteException {
     SharedPreferences.Editor editor = prefs.edit();
     editor.putBoolean("didSetUpTapjoyInstallReferrer", true);
     editor.apply();

     ReferrerDetails referrerDetails = mReferrerClient.getInstallReferrer();
     String referrer = referrerDetails.getInstallReferrer();
     Tapjoy.setInstallReferrer(referrerContext, referrer);
   }
}

3. Important Note

You should either include the IAP purchase receipt with your Tapjoy IAP tracking call (for SDK versions 11.2.0 or higher), or verify that a given IAP is valid using Google Play receipt validation (or whatever is appropriate for the store you are using) before reporting it to Tapjoy. If you do not do this, it is almost certain that your metrics and segmentation will be distorted by fraudulent purchases. This will break numerous Tapjoy capabilities, including the Future Value Map and the ability to target (or exclude) high-spending users with certain kinds of content.

The growth of IAP in freemium apps highlights a critical need for app developers to verify each purchase and guard against fraud. We highly suggest that you use receipt validation in your applications to prevent unauthorized transactions from contaminating your data. That way, you are incorporating valid (and only valid) purchases into your mobile analytics data. If you do not include a receipt parameter, we will assume that you did the receipt validation on your own and accept the purchase as valid.

Using IAP Receipt Verification and tracking your data on the Tapjoy Dashboard is simple and requires a minimal amount of work for app publishers.

You only need to make one single IAP tracking call for each purchase a user makes. By including the receipt parameter, you will eliminate revenue from fraudulent purchases showing up in your dashboard and will ensure that the IAP analytics remain accurate. You can pass the Apple or Google store receipt, along with your Tapjoy IAP tracking call, and Tapjoy’s servers will verify that the transaction is valid before adding it to your dashboard data.

Once you’ve completed receipt validation, you can confidently look at your data set, and Tapjoy’s Future Value Map, and target spenders with IAP promotions and non-spenders with ads in order to truly drive LTV from your users.