Overview

To better support app promotion targeted at Huawei user devices, Ads Kit provides the install referrer capability for advertisers to track promotion channels and attribute conversions.

Install Referrer Capability

Advertisers can use install referrers to analyze the conversion effect of app download ads on app impressions, clicks, downloads, installs, activations, registrations, and purchases. The process is as follows:

  1. An advertiser integrates Ads Kit into their app to obtain the install referrer capability and then releases the app to HUAWEI AppGallery.
  2. The advertiser delivers an app download ad with an install referrer on HUAWEI Ads.
  3. A publisher app requests and displays the ad.
  4. A user taps the ad in the app and can choose to download and install the advertiser's app.
  5. HUAWEI AppGallery writes the install referrer into Ads Kit.
  6. When the user activates the advertiser's app on their device, the advertiser's app obtains the install referrer from Ads Kit.
  7. The advertiser's app on the user device reports an activation event to a third-party tracking platform, which then uses the install referrer to analyze the ad conversion effect.

What You Will Create

In the codelab, you will create an app to integrate Ads Kit. Your app will obtain an install referrer.

What You Will Learn

In this codelab, you will learn how to integrate the install referrer capability of Ads Kit.

Hardware Requirements

A Huawei phone or tablet running EMUI 3.0 or later

Software Requirements

Required Knowledge

Android app development basics

Click here to view and download the sample code of the InstallReferrer-Initial project.
Use Android Studio to open the InstallReferrer-Initial project.

You can integrate the install referrer capability using the SDK provided by Ads Kit. This mode is simple and therefore recommended.

Integrating the SDK

  1. Configure the Maven repository address for the HUAWEI Ads SDK.
    Open the build.gradle file in the root directory of your project. Go to allprojects > repositories and configure the Maven repository address for the SDK.
    allprojects { repositories { google() jcenter() maven { url 'https://developer.huawei.com/repo/' } } }
    In Gradle 7.0 or later, configuration under allprojects > repositories is migrated to the project-level settings.gradle file.
    The following is a configuration example of the settings.gradle file:
    dependencyResolutionManagement { ... repositories { google() jcenter() maven {url 'https://developer.huawei.com/repo/'} } }
  2. Configure build dependencies.
    Add build dependencies to the build.gradle file in the app directory of your project, and replace {version} with the actual version of the HUAWEI Ads SDK. For details, please refer to Version Change History.
    dependencies { implementation 'com.huawei.hms:ads-installreferrer:{version}' }
  3. Synchronize the modified files.
  4. Before building the APK, configure the obfuscation configuration file to prevent the HUAWEI Ads SDK from being obfuscated. Open the obfuscation configuration file proguard-rules.pro in the app directory of your Android project, and add the following code lines to the file to exclude the HUAWEI Ads SDK from obfuscation.
    -keep class com.huawei.hms.ads.** { *; } -keep interface com.huawei.hms.ads.** { *; }

Creating an Install Referrer Status Listener

  1. Implement the onInstallReferrerSetupFinished and onInstallReferrerServiceDisconnected methods of the InstallReferrerStateListener API. The sample code is as follows:
    /** * Create a listener. */ private InstallReferrerStateListener installReferrerStateListener = new InstallReferrerStateListener() { @Override public void onInstallReferrerSetupFinished(int responseCode) { switch (responseCode) { case InstallReferrerClient.InstallReferrerResponse.OK: Log.i(TAG, "connect ads kit ok"); get(); break; case InstallReferrerClient.InstallReferrerResponse.FEATURE_NOT_SUPPORTED: // Service not supported. Download and install the latest version of HMS Core (APK). Log.i(TAG, "FEATURE_NOT_SUPPORTED"); break; case InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE: // Service unavailable. Upgrade the HMS Core (APK) to 2.6.5 or later. Log.i(TAG, "SERVICE_UNAVAILABLE"); break; default: Log.i(TAG, "responseCode: " + responseCode); break; } } @Override public void onInstallReferrerServiceDisconnected() { Log.i(TAG, "onInstallReferrerServiceDisconnected"); } };
  2. After successful connection, call the getInstallReferrer method to obtain the install referrer.
    /** * Obtain the install referrer. */ private void get() { if (null != mReferrerClient) { try { // Obtain the instance of referrerDetails. Do not call this method in the main thread. ReferrerDetails referrerDetails = mReferrerClient.getInstallReferrer(); if (null != referrerDetails && null != mCallback) { // Update install referrer details. mCallback.onSuccess(referrerDetails.getInstallReferrer(), referrerDetails.getReferrerClickTimestampMillisecond(), referrerDetails.getInstallBeginTimestampMillisecond()); } } catch (RemoteException e) { Log.i(TAG, "getInstallReferrer RemoteException: " + e.getMessage()); } catch (IOException e) { Log.i(TAG, "getInstallReferrer IOException: " + e.getMessage()); } finally { disconnect(); } } }

Creating an InstallReferrerClient Instance

Configure and create an InstallReferrerClient instance using builder.

  1. Call InstallReferrerClient.newBuilder to create a Builder instance.
  2. Call build to create an InstallReferrerClient instance.
    mReferrerClient = InstallReferrerClient.newBuilder(mContext).build();

Connecting to the Install Referrer Service

Connect to the install referrer service.

  1. Set the listener ofstartConnectionn toInstallReferrerStateListenerr that has been created.

  2. Call the startConnection method in the subthread to connect to the service.

    mReferrerClient.startConnection(installReferrerStateListener);

Adding an AIDL File

Create a file named IPPSChannelInfoService.aidl in the app/src/main/aidl/com/huawei/android/hms/ppskit/ directory of your project. The package name is com.huawei.android.hms.ppskit. Add the following content to the file:

// IPPSRemoteService.aidl package com.huawei.android.hms.ppskit; /* * Note: Do not modify the method sequence in the AIDL file. */ interface IPPSChannelInfoService { String getChannelInfo(); }

Creating a Class to Implement ServiceConnection

  1. Implement the onServiceConnected method of ServiceConnection.
  2. Call the IPPSChannelInfoService.Stub.asInterface method to obtain IPPSChannelInfoService.
  3. Call the getChannelInfo method to obtain install referrer.
    private final class InstallReferrerServiceConnection implements ServiceConnection { private InstallReferrerServiceConnection() { } @Override public void onServiceConnected(ComponentName componentName, IBinder iBinder) { Log.i(TAG, "onServiceConnected"); mService = IPPSChannelInfoService.Stub.asInterface(iBinder); if (null != mService) { try { //Obtain channel information (in JSON format). String channelJson = mService.getChannelInfo(); Log.i(TAG, "channelJson: " + channelJson); // Parse the channel information. JSONObject jsonObject = new JSONObject(channelJson); // Obtain the install referrer. String installReferrer = jsonObject.optString("channelInfo"); long clickTimestamp = jsonObject.optLong("clickTimestamp", 0); long installTimestamp = jsonObject.optLong("installTimestamp", 0); if (null != mCallback) { // Update install referrer details. mCallback.onSuccess(installReferrer, clickTimestamp, installTimestamp); } else { mCallback.onFail("install referrer is empty"); } } catch (RemoteException e) { Log.e(TAG, "getChannelInfo RemoteException"); mCallback.onFail(e.getMessage()); } catch (Exception e) { Log.e(TAG, "getChannelInfo Exception"); mCallback.onFail(e.getMessage()); } finally { unbindService(); } } } @Override public void onServiceDisconnected(ComponentName componentName) { Log.i(TAG, "onServiceDisconnected"); mService = null; } }

Connecting to the AIDL Service for Obtaining Install Referrer Information

  1. Creates an InstallReferrerServiceConnection instance.
  2. Create an Intent object with the com.huawei.android.hms.CHANNEL_SERVICE action.
  3. Set the package name of Intent to com.huawei.hwid.
  4. Call bindService to connect to the AIDL service for obtaining install referrer information.
    private boolean bindService() { Log.i(TAG, "bindService"); if (null == mContext) { Log.e(TAG, "context is null"); return false; } mServiceConnection = new InstallReferrerServiceConnection(); Intent intent = new Intent(Constants.SERVICE_ACTION); intent.setPackage(Constants.SERVICE_PACKAGE_NAME); // Bind Ads Kit. boolean result = mContext.bindService(intent, mServiceConnection, Context.BIND_AUTO_CREATE); Log.i(TAG, "bindService result: " + result); return result; }

Disconnecting from the AIDL Service for Obtaining Install Referrer Information

After finishing using the AIDL service, you need to disconnect from the service proactively.

private void unbindService() { Log.i(TAG, "unbindService"); if (null == mContext) { Log.e(TAG, "context is null"); return; } if (null != mServiceConnection) { // Unbind Ads Kit. mContext.unbindService(mServiceConnection); mService = null; mContext = null; mCallback = null; } }

Prepare a Huawei mobile phone.

  1. Modify your app for the testing.
    • SDK mode: Call setTest(true) to enable the test mode when creating InstallReferrerClient. The sample code is as follows:
      mReferrerClient = InstallReferrerClient.newBuilder(mContext).setTest(true).build(); mReferrerClient.startConnection(installReferrerStateListener);
    • AIDL mode: During the testing, set the name of the bound AIDL service package to com.huawei.pps.hms.test. The sample code is as follows:
      mServiceConnection = new InstallReferrerServiceConnection(); Intent intent = new Intent(Constants.SERVICE_ACTION); intent.setPackage(Constants.TEST_SERVICE_PACKAGE_NAME); boolean result = mContext.bindService(intent, mServiceConnection, Context.BIND_AUTO_CREATE); Log.i(TAG, "bindService result: " + result);
  2. Compile theInstallReferrer-Initiall project to generate an APK file and install the APK file on the test device.
    Launch your app on the device. The below screen will appear.

  3. Tap Write install referrer for test. On the screen displayed, enter your app package name (see AndroidManifest.xml) and install referrer, and save the settings.
  1. After integrating the install referrer capability into your app, release the app to HUAWEI AppGallery.
  2. Create a promotion task in HUAWEI Ads and set the install referrer, as shown in the following figure.
  3. Obtain the install referrer.
    When your app is activated, it reads the install referrer information and reports the information to a specified analytics platform.

Well done. You have successfully completed this codelab and learned how to integrate the install referrer capability of Ads Kit.

For more information, please refer to related documents.
You can also click here and download the source code.

Code copied