目录

attributionManager (App Attribution Service)

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)

Module Import

import { attributionManager } from '@kit.StoreKit';

AdSourceInfo

Attribution source information registered by the media app or ad platform.

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

SourceType

No

No

Attribution source.

  • 0: impression
  • 1: click

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.

AdTriggerInfo

Information about the conversion events registered by an advertiser.

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.

SourceType

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.

attributionManager.registerSource

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

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.`
      })
    }
  }
}

attributionManager.registerTrigger

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

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.`
      })
    }
  }
}