This module enables media apps and ad platforms to register ad attribution sources with the app attribution service, and allows advertisers and monitoring platforms to register conversion events with the app attribution service.
Exceptions need to be captured when an API is called.
Start version: 5.0.0(12)
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Start version: 5.0.0(12)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| adTechId | string | No | No | ID of the attribution role as an ad platform. It is an identifier of the ad platform that owns the ad task related to the registered attribution source. This ID is assigned by the app attribution service when an ad platform registers an attribution role on the cloud platform of the app attribution service. It has a fixed length of 8 characters. |
| campaignId | string | No | No | Marketing task ID, which is the ID of the ad task corresponding to the registered attribution source. The value contains a maximum of 6 characters. |
| destinationId | string | No | No | ID of the app released by an advertiser on AppGallery. The value contains a maximum of 64 characters. NOTE: For details about how to obtain your app ID, please refer to Viewing App Basic Information. |
| sourceType | No | No | Attribution source.
| |
| mmpIds | string[] | No | Yes | ID of the attribution role as a monitoring platform used for this particular ad delivery task. A maximum of two IDs can be configured. Each ID contains 8 characters. If the caller passes the monitoring platform ID, the app attribution service will post back the attribution result to the monitoring platform. Without this ID, the monitoring platform cannot receive the attribution result. |
| serviceTag | string | No | Yes | Business information that an ad platform focuses on, such as creatives and assets. The value should not exceed 32 characters. If the caller specifies serviceTag, the app attribution service will add this parameter to a trustlist and open it to the ad platform. If the caller does not specify serviceTag, the ad platform will not receive it. |
| nonce | string | No | No | UUID in lowercase, without hyphens (-), used for signature calculations. The value of nonce is unique for each ad request and has a fixed length of 32 characters. For each adTechId, a single nonce can be associated with up to five impressions and five clicks. |
| timestamp | number | No | No | Unix timestamp in milliseconds, representing the time when the ad is requested, that is, the time when the ad is delivered. The deviation from the current time should not exceed 10 minutes. |
| signature | string | No | No | Signature. An ad platform or a media app generates a signature based on the ad information and attribution source signature calculation rules. The value contains a maximum of 800 characters. |
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Start version: 5.0.0(12)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| businessScene | number | No | Yes | Business scenario. The value ranges from 0 to 99. NOTE: This parameter is reserved for you to pass additional information. You can choose to set it or not. |
| triggerData | number | No | No | Conversion event ID. For standard conversion events, the value ranges from 1 to 200. For custom conversion events, the value ranges from 501 to 600. |
Enumerated attribution sources.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Start version: 5.0.0(12)
| Name | Value | Description |
|---|---|---|
| IMPRESSION | 0 | Impression. |
| CLICK | 1 | Click. |
registerSource(adSourceInfo: AdSourceInfo): Promise<void>
Registers attribution sources, which is called by a media app or an ad platform. This API returns the result asynchronously through a promise.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Start version: 5.0.0(12)
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| adSourceInfo | Yes | Attribution source information registered by the media app or ad platform. |
Returns:
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes:
For details about the error codes, please refer to ArkTS API Error Codes.
| Error Code | Error Message |
|---|---|
| 401 | Parameter error. |
| 1009300001 | The specified service extension connect failed. |
| 1009300002 | System internal error. |
| 1009300003 | The identity check error. |
| 1009300004 | The sign check error. |
Example:
import { hilog } from '@kit.PerformanceAnalysisKit';
import { attributionManager } from '@kit.StoreKit';
import { SignUtil } from '../common/utils/SignUtil'; // Refer to the signature generation code in the appendix of the development guide.
import { util } from '@kit.ArkTS';
import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
const TAG: string = 'Attribution';
class Attribution {
async registerSource(): Promise<void> {
try {
// Private key corresponding to the public key provided during role registration on the cloud platform of the app attribution service.
let privateKey: string =" ";
// Allocated by the app attribution service during role registration on the cloud platform of the app attribution service.
let adTechId: string = '20****8';
// ID of the ad task created by the ad platform.
let campaignId: string = '123456';
// ID of the advertiser's app released on AppGallery, without letter C.
let destinationId: string = '691****4';
// ID of the monitoring platform.
let mmpIds: string[] = ['2f76e815'];
// Business information that the ad platform focuses on.
let serviceTag: string = 'testServiceTag';
// UUID in lowercase, without hyphens (-).
let nonce: string = util.generateRandomUUID().replace(/-/g, '');
// Timestamp.
let timestamp: number = Date.now()
let adSourceInfo: attributionManager.AdSourceInfo = {
adTechId: adTechId,
campaignId: campaignId,
destinationId: destinationId,
// Attribution source: impression.
sourceType: attributionManager.SourceType.IMPRESSION,
mmpIds: mmpIds,
serviceTag: serviceTag,
nonce: nonce,
timestamp: timestamp,
// Signature.
signature: await SignUtil.getSign(SignUtil.genSignContent(adTechId, campaignId, destinationId, mmpIds, serviceTag, nonce, timestamp), privateKey)
};
attributionManager.registerSource(adSourceInfo).then(() => {
hilog.info(0, TAG, 'Succeeded in registering source.');
promptAction.showToast({
message: 'registerSource success.'
})
}).catch((error: BusinessError) => {
hilog.error(0, TAG, `registerSource error.code is ${error.code}, message is ${error.message}`);
promptAction.showToast({
message: `registerSource failed.`
})
})
} catch (error) {
hilog.error(0, TAG, `registerSource error.code is ${error.code}, message is ${error.message}`);
promptAction.showToast({
message: `registerSource failed.`
})
}
}
} registerTrigger(adTriggerInfo: AdTriggerInfo): Promise<void>
Registers conversion events, which is called by advertisers. This API returns the result asynchronously through a promise.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Start version: 5.0.0(12)
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| adTriggerInfo | Yes | Conversion event information. |
Returns:
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes:
For details about the error codes, please refer to ArkTS API Error Codes.
| Error Code | Error Message |
|---|---|
| 401 | Parameter error. |
| 1009300001 | The specified service extension connect failed. |
| 1009300002 | System internal error. |
| 1009300003 | The identity check error. |
Example:
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { attributionManager } from '@kit.StoreKit';
import { promptAction } from '@kit.ArkUI';
const TAG: string = 'Attribution';
class Attribution {
registerTrigger(): void {
try {
let adTriggerInfo: attributionManager.AdTriggerInfo = {
businessScene: 5,
// Conversion event ID, which is obtained from the cloud platform of the app attribution service.
triggerData: 123
};
attributionManager.registerTrigger(adTriggerInfo).then(() => {
hilog.info(0, TAG, 'Succeeded in registering triggerdata.');
promptAction.showToast({
message: 'registerTrigger success.'
})
}).catch((error: BusinessError) => {
hilog.error(0, TAG, `registerTrigger error.code is ${error.code}, message is ${error.message}`);
promptAction.showToast({
message: `registerTrigger failed.`
})
})
} catch (error) {
hilog.error(0, TAG, `registerTrigger error.code is ${error.code}, message is ${error.message}`);
promptAction.showToast({
message: `registerTrigger failed.`
})
}
}
}