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.
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 integrate Ads Kit. Your app will obtain an install referrer.
In this codelab, you will learn how to integrate the install referrer capability of Ads Kit.
A Huawei phone or tablet running EMUI 3.0 or later
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.
allprojects {
repositories {
google()
jcenter()
maven { url 'https://developer.huawei.com/repo/' }
}
}
dependencyResolutionManagement {
...
repositories {
google()
jcenter()
maven {url 'https://developer.huawei.com/repo/'}
}
}
dependencies {
implementation 'com.huawei.hms:ads-installreferrer:{version}'
}
-keep class com.huawei.hms.ads.** { *; }
-keep interface com.huawei.hms.ads.** { *; }
/**
* 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");
}
};
/**
* 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();
}
}
}
Configure and create an InstallReferrerClient instance using builder.
mReferrerClient = InstallReferrerClient.newBuilder(mContext).build();
Connect to the install referrer service.
Set the listener ofstartConnectionn toInstallReferrerStateListenerr that has been created.
Call the startConnection method in the subthread to connect to the service.
mReferrerClient.startConnection(installReferrerStateListener);
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();
}
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;
}
}
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;
}
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.
mReferrerClient = InstallReferrerClient.newBuilder(mContext).setTest(true).build();
mReferrerClient.startConnection(installReferrerStateListener);
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);
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.
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.