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.
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:
In the codelab, you will create an app to access HUAWEI Ads. Your app will obtain an install referrer.
In this codelab, you will learn how to integrate the install referrer capability of HUAWEI Ads Kit.
A Huawei phone or tablet running Android
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.
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.
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:
You can click the button below to download the source code.