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 this 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-Kotlin project.

Download source code

Use Android Studio to open the InstallReferrer-Kotlin 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.

build.gradle

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.

app/build.gradle

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

private val mInstallReferrerStateListener: InstallReferrerStateListener = object : InstallReferrerStateListener { override fun onInstallReferrerSetupFinished(responseCode: Int) { when (responseCode) { OK -> { Log.i(TAG, "connect ads kit ok") get() } FEATURE_NOT_SUPPORTED -> Log.i(TAG, "FEATURE_NOT_SUPPORTED") SERVICE_UNAVAILABLE -> Log.i(TAG, "SERVICE_UNAVAILABLE") else -> Log.i(TAG, "responseCode: $responseCode") } } override fun onInstallReferrerServiceDisconnected() { Log.i(TAG, "onInstallReferrerServiceDisconnected") } }

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

InstallReferrerSdkUtil.kt

private fun get() { mReferrerClient?.let { try { val mReferrerDetails: ReferrerDetails = it.installReferrer mReferrerDetails.apply { mCallback?.apply { onSuccess( installReferrer, referrerClickTimestampMillisecond, installBeginTimestampMillisecond ) } } } catch (e: RemoteException) { Log.i(TAG, "getInstallReferrer RemoteException: ${e.message}") } catch (e: IOException) { Log.i(TAG, "getInstallReferrer IOException: ${e.message}") } 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.kt

mContext?.let { mReferrerClient = InstallReferrerClient.newBuilder(it).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.kt

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

override fun onServiceConnected(name: ComponentName?, mIBinder: IBinder?) { Log.i(TAG, "onServiceConnected") mService = IPPSChannelInfoService.Stub.asInterface(mIBinder) mService?.let { try { val channelJson = it.channelInfo Log.i(TAG, "channelJson: $channelJson") val jsonObject = JSONObject(channelJson) jsonObject.apply { val installReferrer = optString("channelInfo") val clickTimestamp = optLong("clickTimestamp", 0) val installTimestamp = optLong("installTimestamp",0) if (!TextUtils.isEmpty(installReferrer)) { mCallback?.onSuccess(installReferrer, clickTimestamp, installTimestamp) } else { mCallback?.onFail("install referrer is empty") } } } catch (e: Exception) { Log.e(TAG, "getChannelInfo Exception") mCallback?.onFail(e.message) } finally { unbindService() } } } override fun onServiceDisconnected(name: 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.kt

private fun bindService(): Boolean { Log.i(TAG, "bindService") if (null == mContext) { Log.e(TAG, "context is null") return false } val mResult: Boolean mServiceConnection = InstallReferrerServiceConnection() val intent = Intent(SERVICE_ACTION) intent.setPackage(SERVICE_PACKAGE_NAME) mResult = mContext?.bindService(intent, mServiceConnection!!, Context.BIND_AUTO_CREATE)!! Log.i(TAG, "bindService result: $mResult") return mResult }

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

private fun unbindService() { mServiceConnection?.let{ unbindService(it) } }

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:

mContext?.let { mReferrerClient = InstallReferrerClient.newBuilder(it).build() mReferrerClient?.startConnection(mInstallReferrerStateListener) }

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 = InstallReferrerServiceConnection() val intent = Intent(Constants.SERVICE_ACTION) intent.setPackage(Constants.TEST_SERVICE_PACKAGE_NAME) val 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.
  4. 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