This module offers debugging capabilities that include verifying attribution sources, configuring attribution result postback, and initiating the postback of attribution results.
Exceptions need to be captured when an API is called.
Since: 5.0.0(12)
attributionTestManager.validateSource
validateSource(adSourceInfo: AdSourceInfo, publicKey: string): Promise<void>
Verifies attribution sources registered by the media app or distribution platform. This API uses a promise to return the result.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Since: 5.0.0(12)
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| adSourceInfo | AdSourceInfo | Yes | Attribution source information registered by the media app or distribution platform. |
| publicKey | string | Yes | Public key obtained from Generating a Key Pair. It is provided for the cloud platform of the app attribution service during attribution role registration. |
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. |
| 1009300101 | AdTechId is missing in the request. |
| 1009300102 | CampaignId is missing in the request. |
| 1009300104 | DestinationId is missing in the request. |
| 1009300105 | SourceType is missing in the request. |
| 1009300106 | Nonce is missing in the request. |
| 1009300107 | Timestamp is missing in the request. |
| 1009300108 | Signature is missing in the request. |
| 1009300111 | AdSourceInfo is missing in the request. |
| 1009300112 | PublicKey is missing in the request. |
| 1009300114 | The signature verification failed in the testing environment. |
Example:
import { hilog } from '@kit.PerformanceAnalysisKit';
import { attributionTestManager } from '@kit.AppGalleryKit';
// Refer to the code of the signature generation method in the appendix of the development guide.
import { SignUtil } from '../common/utils/SignUtil';
import { util } from '@kit.ArkTS';
import { deviceInfo } from '@kit.BasicServicesKit';
const TAG: string = 'AttributionTest';
class AttributionTest {
async validateSource(): Promise<void> {
try {
// Public key and corresponding private key provided during role registration on the cloud platform of the app attribution service. You can customize the values for debugging purposes.
let privateKey: string = '';
let publicKey: string = '';
// Allocated by the app attribution service when an ad ecosystem partner role is registered on the cloud platform of the app attribution service.
let adTechId: string = '12345678';
// ID of the marketing task created by the distribution platform.
let campaignId: string = ' ';
let osApiVersion: number = deviceInfo.sdkApiVersion;
if (osApiVersion >= 22) {
campaignId = '1*******9';
} else {
campaignId = '1****6';
}
// ID of the developer's app released on AppGallery, without letter C.
let destinationId: string = '102345678';
// ID of the attribution monitoring platform.
let mmpIds: string[] = ['12345678', '23456789'];
// Business information relevant to the distribution platform.
let serviceTag: string = 'testServiceTag';
// Random string without hyphens (-), used for signature calculations.
let nonce: string = util.generateRandomUUID().replace(/-/g, '');
// Timestamp.
let timestamp: number = Date.now();
let adSourceInfo: attributionTestManager.AdSourceInfo = {
adTechId: adTechId,
campaignId: campaignId,
destinationId: destinationId,
// Impression.
sourceType: attributionTestManager.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)
};
await attributionTestManager.validateSource(adSourceInfo, publicKey);
hilog.info(0, TAG, 'Succeeded in validating source.');
} catch (error) {
hilog.error(0, TAG, `validateSource error.code is ${error.code}, message is ${error.message}`);
}
}
} attributionTestManager.setPostback
setPostback(postbackInfo: PostbackInfo): Promise<void>
Sets attribution result information that can be posted back. It is used for verifying the validity of triggerData and setting attribution result information that can be posted back for debugging purposes. This API uses a promise to return the result.
For a single adTechId, the number of postbackInfo records to be posted back for debugging purposes should not exceed 5.
For a single device, the number of postbackInfo records to be posted back for debugging purposes should not exceed 100.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Since: 5.0.0(12)
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| postbackInfo | PostbackInfo | Yes | Attribution result information that can be posted back. |
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. |
| 1009300101 | AdTechId is missing in the request. |
| 1009300102 | CampaignId is missing in the request. |
| 1009300103 | SourceId is missing in the request. |
| 1009300104 | DestinationId is missing in the request. |
| 1009300109 | TriggerData is missing in the request. |
| 1009300110 | PostbackUrl is missing in the request. |
| 1009300113 | PostbackInfo is missing in the request. |
| 1009300115 | Too many postbacks setting to the testing environment. |
Example:
import { hilog } from '@kit.PerformanceAnalysisKit';
import { attributionTestManager } from '@kit.AppGalleryKit';
import { deviceInfo } from '@kit.BasicServicesKit';
const TAG: string = 'Attributiontest';
@Entry
@Component
struct Attribution {
build() {
Column({ space: 20 }) {
Button("set_postback")
.onClick(() => {
this.setPostback();
})
.width('100%')
}
.margin(16)
.height('100%')
.justifyContent(FlexAlign.Center)
}
async setPostback(): Promise<void> {
try {
let postbackInfo: attributionTestManager.PostbackInfo = {
// Allocated by the app attribution service when an ad ecosystem partner role is registered on the cloud platform of the app attribution service.
adTechId: '12345678',
// ID of the marketing task created by the distribution platform.
campaignId: ' ',
// Media app ID.
sourceId: '112345678',
// ID of the developer's app released on AppGallery, without letter C.
destinationId: '102345678',
// Business information relevant to the distribution platform.
serviceTag: 'testServiceTag',
// Business scene value.
businessScene: 5,
// Conversion event ID.
triggerData: 123,
// URL for receiving attribution results. HTTPS is recommended.
postbackUrl: 'https://xxx.com'
};
let osApiVersion: number = deviceInfo.sdkApiVersion;
if (osApiVersion >= 22) {
postbackInfo.campaignId = '1*******9';
} else {
postbackInfo.campaignId = '1****6';
}
// Set attribution result information that can be posted back.
attributionTestManager.setPostback(postbackInfo).then(() => {
hilog.info(0, TAG, 'Succeeded in setting postback.');
}).catch((error: BusinessError) => {
hilog.error(0, TAG, `setPostback onError.code is ${error.code}, message is ${error.message}`);
})
} catch (error) {
hilog.error(0, TAG, `setPostback onError.code is ${error.code}, message is ${error.message}`);
}
}
} attributionTestManager.flushPostbacks
flushPostbacks(adTechId: string): Promise<void>
Triggers attribution result postback. It checks whether the logic of your server for receiving and processing the attribution result is correct. This API uses a promise to return the result.
On a single device, this API can be called at most once every 5 seconds.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Since: 5.0.0(12)
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| adTechId | string | Yes | Attribution role ID of a distribution platform. This identifier specifies the distribution platform to which the marketing task of the registered attribution source belongs. The value must consist of eight characters. Use the value of adTechId that is successfully set in the setPostback() API. Note: The debugging process does not depend on the registration on the cloud platform. You can use a virtual value of adTechId. |
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. |
| 1009300101 | AdTechId is missing in the request. |
| 1009300116 | There is no postback to be sent of this adTechId. |
| 1009300117 | Failed to send postbacks to the postbackUrl. |
| 1009300119 | Network error. |
| 1009300120 | Request too frequent. |
Example:
import { hilog } from '@kit.PerformanceAnalysisKit';
import {attributionTestManager } from '@kit.AppGalleryKit';
const TAG: string = 'AttributionTest';
@Entry
@Component
struct Attribution {
build() {
Column({ space: 20 }) {
Button("flush_postbacks")
.id('flush_postbacks')
.onClick(() => {
this.flushPostbacks();
})
.width('100%')
}
.margin(16)
.height('100%')
.justifyContent(FlexAlign.Center)
}
async flushPostbacks(): Promise<void> {
try {
// Attribution role ID of a distribution platform.
let adTechId: string = '1******8';
// Trigger attribution result postback.
await attributionTestManager.flushPostbacks(adTechId);
hilog.info(0, TAG, 'flushPostbacks success.');
} catch (error) {
hilog.error(0, TAG, `flushPostbacks error. code is ${error.code}, message is ${error.message}`);
}
}
} AdSourceInfo
Attribution source information registered by the media app or distribution platform.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Since: 5.0.0(12)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| adTechId | string | No | No | Attribution role ID of a distribution platform. This identifier specifies the distribution platform to which the marketing task of the registered attribution source belongs. This ID is assigned by the app attribution service when a distribution platform registers an attribution role on the cloud platform of the app attribution service. It has a fixed length of eight characters. Note: The debugging process does not depend on the registration on the cloud platform. You can use a virtual value of adTechId. |
| campaignId | string | No | No | Marketing task ID, which is the ID of the marketing task corresponding to the registered attribution source. The value contains a maximum of six characters. Note: For 6.0.2(22) and later versions, the maximum value length of this parameter will change from six to nine characters. |
| destinationId | string | No | No | ID of the app released 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 | SourceType | No | No | Attribution source. 0: impression 1: click |
| mmpIds | string[] | No | Yes | Attribution role ID of the attribution monitoring platform used in the current ad delivery task. A maximum of two IDs can be configured. Each ID contains eight characters. If the caller passes the attribution monitoring platform ID, the app attribution service will post back the attribution result to the attribution monitoring platform. Without this ID, the attribution monitoring platform cannot receive the attribution result. |
| serviceTag | string | No | Yes | Business information relevant to the distribution platform, such as information about creatives and assets. The value should not exceed 32 characters. If the caller passes serviceTag, the app attribution service will post back serviceTag to the distribution platform after the permission is enabled. |
| nonce | string | No | No | Random string, used for signature calculations. The value of nonce is unique for each ad request and has a fixed length of 32 characters. |
| timestamp | number | No | No | Time when the ad is requested, that is, the time when the ad is delivered. It is required that the value not deviate from the current time by more than 10 minutes. The value is a Unix timestamp in milliseconds. |
| signature | string | No | No | Signature. A distribution platform or media app generates a signature based on the ad information and attribution source signature calculation rules. The value contains a maximum of 800 characters. |
PostbackInfo
Data to be posted back.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AppGalleryService.AttributionManager
Since: 5.0.0(12)
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| adTechId | string | No | No | Attribution role ID of a distribution platform. This identifier specifies the distribution platform to which the marketing task of the registered attribution source belongs. Use the value of adTechId that is successfully set in the setPostback() API. Note: The debugging process does not depend on the registration on the cloud platform. You can use a virtual value of adTechId. |
| campaignId | string | No | No | Marketing task ID, which is the ID of the marketing task corresponding to the registered attribution source. The value contains a maximum of six characters. Note: For 6.0.2(22) and later versions, the maximum value length of this parameter will change from six to nine characters. |
| sourceId | string | No | No | Media app ID. The value contains a maximum of 64 characters. |
| destinationId | string | No | No | ID of the app released on AppGallery. The value contains a maximum of 64 characters. |
| serviceTag | string | No | Yes | Business information relevant to the distribution platform, such as information about creatives and assets. The value should not exceed 32 characters. If the caller passes serviceTag, the app attribution service will post back serviceTag to the distribution platform after the permission is enabled. |
| businessScene | number | No | Yes | Business scene value, which is used to identify the business scenarios of a developer when the developer registers conversion events. The value ranges from 0 to 99. |
| triggerData | number | No | No | Conversion event ID. The value ranges from 0 to 999. |
| postbackUrl | string | No | No | URL for receiving attribution results. HTTPS is recommended. |