Overview

To better support app promotion targeted at Huawei devices, HUAWEI 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 HUAWEI 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 media source's app (media app) requests and displays the ad.
  4. A user clicks the ad in the media app and can choose to download and install the advertiser's app.
  5. HUAWEI AppGallery writes the install referrer into HUAWEI Ads Kit.
  6. When the user activates the advertiser's app on their device, the advertiser's app obtains the install referrer from HUAWEI 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 access HUAWEI Ads. 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 HUAWEI Ads Kit.

Hardware Requirements

A Huawei phone or tablet running Android

Software Requirements

HMS Core (APK) 2.6.5 or later.
To view the HMS Core (APK) version on a device, go to Settings > Apps > Apps and search for HMS Core.

Download the InstallReferrer-Initial project.

Download source code

Use Android Studio to open the InstallReferrer-Initial project.

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

1. Integrate the SDK.

Step 1: Configure the Maven repository address for the HUAWEI Ads SDK.

Open the build.gradle file in the root directory of your Android Studio 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/' } } }

Step 2: Configure build dependencies.

Open the build.gradle file in the app directory. Configure build dependencies, and replace {version} with the latest version of HUAWEI Ads SDK. For details, please refer to Version Change History.

dependencies { implementation 'com.huawei.hms:ads-installreferrer:{version}' }

Step 3: Synchronize the modified files.

Step 4: (Mandatory) Configure the obfuscation scripts.

app/proguard-rules.pro

-keep class com.huawei.hms.ads.** { *; } -keep interface com.huawei.hms.ads.** { *; }

2. Create an install referrer status listener.

Implement the onInstallReferrerSetupFinished and onInstallReferrerServiceDisconnected methods of the InstallReferrerStateListener API. The sample code is as follows:

InstallReferrerSdkUtil.java

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: Log.i(TAG, "FEATURE_NOT_SUPPORTED"); break; case InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE: Log.i(TAG, "SERVICE_UNAVAILABLE"); break; default: Log.i(TAG, "responseCode: " + responseCode); break; } } @Override public void onInstallReferrerServiceDisconnected() { Log.i(TAG, "onInstallReferrerServiceDisconnected"); } };

After successful connection, call the getInstallReferrer method to obtain the install referrer parameter.

InstallReferrerSdkUtil.java

private void get() { if (null != mReferrerClient) { try { ReferrerDetails referrerDetails = mReferrerClient.getInstallReferrer(); if (null != referrerDetails && null != mCallback) { mCallback.onSuccuss(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(); } } }

3. Create an InstallReferrerClient instance.

Configure and create an InstallReferrerClient instance using builder.

Development procedure:

Step 1: Call InstallReferrerClient.newBuilder to create a Builder instance.

Step 2: Call build to create an InstallReferrerClient instance.

InstallReferrerSdkUtil.java

mReferrerClient = InstallReferrerClient.newBuilder(mContext).build();

4. Connect to the install referrer service.

Do not call this method in a main thread.

Development procedure:

Step 1: Set the listener of startConnection to InstallReferrerStateListener that has been created.

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

InstallReferrerSdkUtil.java

mReferrerClient.startConnection(installReferrerStateListener);

1. Add an AIDL file.

Add the IPPSChannelInfoService.aidl file in the project. The package name is com.huawei.android.hms.ppskit. The file contains the following content:

app/src/main/aidl/com/huawei/android/hms/ppskit/IPPSChannelInfoService.aidl

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

2. Create a class to implement ServiceConnection.

Development procedure:

Step 1: Implement the onServiceConnected method of ServiceConnection.

Step 2: Call the IPPSChannelInfoService.Stub.asInterface method to obtain IPPSChannelInfoService.

Step 3: Call the getChannelInfo method to obtain install referrer information.

InstallReferrerAidlUtil.java

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 { String channelJson = mService.getChannelInfo(); Log.i(TAG, "channelJson: " + channelJson); JSONObject jsonObject = new JSONObject(channelJson); String installReferrer = jsonObject.optString("channelInfo"); long clickTimestamp = jsonObject.optLong("clickTimestamp", 0); long installTimestamp = jsonObject.optLong("installTimestamp", 0); if (null != mCallback) { mCallback.onSuccuss(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 Excepition"); mCallback.onFail(e.getMessage()); } finally { unbindService(); } } } @Override public void onServiceDisconnected(ComponentName componentName) { Log.i(TAG, "onServiceDisconnected"); mService = null; } }

3. Connect to the AIDL service for obtaining install referrer information.

Development procedure:

Step 1: Create an InstallReferrerServiceConnection instance.

Step 2: Create the Intent object with the com.huawei.android.hms.CHANNEL_SERVICE action.

Step 3: Set the package name of Intent to com.huawei.hwid.

Step 4: Call bindService to connect to the AIDL service for obtaining install referrer information.

InstallReferrerAidlUtil.java

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); boolean result = mContext.bindService(intent, mServiceConnection, Context.BIND_AUTO_CREATE); Log.i(TAG, "bindService result: " + result); return result; }

4. Disconnect from the AIDL service for obtaining install referrer information.

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

InstallReferrerAidlUtil.java

private void unbindService() { if (null != mServiceConnection) { unbindService(mServiceConnection); } }

Prepare a Huawei phone running HMS Core (APK) 2.6.5 or later.
1. Modify your app for the testing.

SDK mode

When creating InstallReferrerClient, set the test mode by calling setTest(true), as shown in the following:

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, as shown in the following:

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 the InstallReferrer-Initial project to generate an APK file and install the APK file on a device.
3. Run your app on the device. The page shown in the following figure is displayed.

4. Click Write install referrer for test. The following page is 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 on the HUAWEI Ads console and set the install referrer parameter, as shown in the following figure.
  3. Read the install referrer.

When your app is activated, it reads the install referrer and reports the information to a custom analytics platform.

Well done. You have successfully completed this codelab and learned how to:

For more information, please click the following link:

Related documents

You can click the button below to download the source code.

Download source code

Code copied