Current Path:Home » Documents » API Docs » The text

Coraool MiniSDK Development Guide

1. Introduction

Coraool MiniSDK integrates the tracking system and API calling system.

2. Docking process

Overall process description:

  • STEP1: Developers access Coraool MiniSDK and call custom buried points to report
    • 1. Initialization
    • 2. Set login status
    • 3. Customized buried points
  • STEP2: Call API to obtain data and obtain data.

3. Instructions for use

3.1 scriptIntroduction plan

将 SDK 放置入本地项目中,并在 app.js 引入SDK,例如:import "./coraool-mini-sdk-2.3.3.js"
VersionDateReleaseNotesSDK
20241010Version 2.3.0 Updates:
1. Enhance the Compatibility of the setUserId Method
https://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-mini-sdk-2.3.3.js
20240729
Version 2.3.0 Updates:
1. The GTP information is optimized
https://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-mini-sdk-2.3.0.js
20240716Version 2.2.6 Updates:
1. Added getDeviceId, the method for obtaining the device ID. For details, see 4.15
https://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-mini-sdk-2.2.6.js
20240703Added AB ability, see Chapter 4.19 for details window.CORA_SDK.abTest.getBucket() is used to get the experiment name window.CORA_SDK.abTest.getBucketObject() is used to obtain the full data of the experimenthttps://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-mini-sdk-2.2.0.js
20240520Improve system stabilityhttps://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-mini-sdk-2.1.1.js
20240424Improve system stabilityhttps://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-mini-sdk-2.1.0.js
20240318Improve system stabilityhttps://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-mini-sdk-1.1.0.js
// 在app.js内
import "./utils/sdk/coraool-mini-sdk-x.x.x.js"

  3.2 Add server domain name whitelist

Please add the following domain name to the server domain name whitelist of your mini program

  • https://track.coraoolapis.com
  • https://api.coraoolapis.com
  • https://digiplus.coraoolstatic.com

3.3 Call example

1. Step 1: Initialization

my.CORA_SDK.initialize({
    AppId: "appId", // 目前传测试值,后续在coraool申请
    AppKey: "appKey",
    AppSec: "appSec",
    abTest: true // true 去请求abTest接⼝,false不请求
})

2. Step 2: Set login status

Set login status ( login, called when logging out)

userId: userId, pass the real userId when logging in, and pass empty when logging out.”

afId: additional information – e.g. afId

my.CORA_SDK.setUserId({
    userId: "userId", // 用户Id,登录时传真实的userId,登出时传空""
    afId: "afId", // 额外信息 - 例如afId
});  

3. Step 3: API call example

  3.1 Invoke method call

apiName: “home.game.ranking” This value is always passed when obtaining the Ranking list.

apiVersion api version, currently only supports 1.0.0

// 调用
const res = my.CORA_SDK.invoke({
    apiName: "home.game.ranking", // 获取Ranking列表的时候 固定传该值
    apiVersion:"1.0.0",    // 目前只支持 1.0.0
});

3.2 Track buried points

eventType: CLICK click, EXPOSE exposure PAGE page CUSTOM customization (if not filled in, it is customized)

my.CORA_SDK.track("eventName", {
    eventType: "PAGE", // CLICK 点击 EXPOSE曝光 PAGE页面 CUSTOM自定义(不填为自定义)
    "customClickKey1": "customClickValue1", // 自定义key: value
    "customClickKey2": "customClickValue2", // 自定义key: value
});

3.3 AB Test Experiment

  1. getBucket

This method is used to obtain the experimental bucket corresponding to the experiment

my.CORA_SDK.abTest.getBucket("xxx_layer").then((res) => {
    console.log(res) // { bucket:"xxx"}
})
  1. getBucketObject

This method is used to obtain the experimental bucket corresponding to the experiment (more complete data)

my.CORA_SDK.abTest.getBucketObject("xxx_layer").then((res) => {
    console.log(res)
})
/*
  res:{
        "name": "xxx_layer01",
        "version": "11"
        "bucket": "base",
        "bucketVersion": "11",
     }
*/

4. API description

4.1 initialize

    SDK initialization, parameter description:

Field nametypeIs it necessaryexplainillustrate
AppIdstringyesAppId of SDK initialization parameterIt is allocated when the business party accesses the SDK. It is allocated independently by different ends and is globally unique.
AppKeystringyesunique application identifierAllocated when the business party accesses the SDK, one for each end
AppSecstringyesEncrypted string for data exchangeAllocated when the business party accesses the SDK, one for each end
abTestbooleanWhether to enable ABTest functionDefault is false

  Example:

my.CORA_SDK.initialize({
    AppId: "appId", // 目前传测试值,后续在coraool申请
    AppKey: "appKey",
    AppSec: "appSec",
    abTest: true // true 去请求abTest接口,false不请求
})

4.2 setUserId

    Set userId, afId, parameter description:

Field nametypeIs it necessaryexplain
userIdstringyesThe userId of the user. If not logged in, pass an empty string.
afIdstringyesThe user’s afId. If the afId cannot be obtained, an empty string is passed.

Example:

my.CORA_SDK.setUserId({    userId: "112332123_ef_123", // 用户的userId
    afId: "2112332123_ef_1231_afId_3123", // 额外信息 - 用户的afId
}); 

4.3 Invoke

call api

my.CORA_SDK.invoke({
    apiName: "binggo.homePage.ranking",
    apiVersion: "1.0.0",
    params: {} // 无 params 可不写此行
})

  Input instructions:

Field nametypeIs it necessaryexplain
apiNamestringyesExample of api name: Get Ranking list data: apiName: “home.game.ranking”
apiVersionstringnoIf not uploaded, the default version is 1.0.0

 Parameter description:

{
    version: "75a7ff8403ccb7f4b26028ba7c5a6fac", // 版本号
    ranking: [{
       gameId: "CrazyTime0000002", // 游戏Id
       gameTop: "top1 Slot", // 游戏排行
       gameType: 17, // 游戏类型
       likeCnt: 2001, // 收藏数
       platformId: "108", // 游戏厅Id
       tags: ['MostPlayed',...], // 推荐标签
       },
       {...}
    ],
    track: { // 埋点数据 (AF上报数据,与本次track不冲突)
       expLayer: 'NEWUSER', // 实验参数,用于埋点上报  
       expBucket: '74',  // 实验参数,用于埋点上报 
       expAlg: 'ggr', // 实验参数,用于埋点上报
       expExtra: null // 实验参数,用于埋点上报
    }
}

  Parameter description:

Field nametypeexplain
ObjectResults returned by ranking list
versionstringversion number
rankingArraySort data
gameIdstringGameId
platformIdstringGame arcadeId
gameTopstring | nullGame ranking
gameTypenumbergame type
likeCntnumber| nullNumber of collections
tagsstring[] | nullRecommend Signature,
trackBuried data
expLayerstringExperimental parameters, used to bury and report
the user’s new and old user ID NEWUSER (new user) / OLDUSER (old user) / BASE (if neither userId nor device ID is passed, BASE will be returned)
expBucketstringExperimental parameters, used for buried point reporting
expAlgstringExperimental parameters, used for buried point reporting
expExtrastring | nullExtended parameters for hidden point reporting

4.4 Track

Custom buried points

The application scenarios of custom buried points are very wide, and they need to be used flexibly to avoid overreporting and false positives of data.

my.CORA_SDK.track("eventName", {
    eventType: "PAGE", // CLICK 点击 EXPOSE曝光 PAGE页面 CUSTOM自定义(不填为自定义)
    customClickKey1: "customClickValue1",
    customClickKey2: "customClickValue2",
    customClickKey3: "customClickValue3",
});
Field nametypeIs it necessaryexplain
eventNamestringyesEvent name (fill in the specification)
eventValueParamsObjectnoevent object
Field nametypeIs it necessaryexplain
pageNamestringyesPage name
eventTypestringnoCLICK click, EXPOSE exposure, PAGE page, CUSTOM custom event unfilled/empty custom event
customxxxstringnoCustom key value

4.5 trackPageStart

Enter the page to bury points. If the point burying method is manual mode, you can start burying points yourself.

// my.CORA_SDK.trackPageStart(eventName: string, eventValue: Object)

// 使用实例
my.CORA_SDK.trackPageStart("eventName", {
   key: "value",
})

Parameter Description:

Field nametypeIs it necessaryexplain
eventNamestringyesevent name
eventValueObjectnoevent object

4.6 trackPageEnd

Leave the page buried point, leave the page buried point (used in conjunction with trackPageStart, the parameters are the same)

// my.CORA_SDK.trackPageEnd(eventName: string, eventValue: Object)

// 使用实例
my.CORA_SDK.trackPageEnd("eventName", {
   key: "value",
})

4.7 setCustomDeviceId

Support custom device ID

my.CORA_SDK.setCustomDeviceId("xxid");

4.8 setPageCollectionMode

Set the burying mode and support two burying modes: manual and automatic.

// my.CORA_SDK.setPageCollectionMode(mode: "AUTO" | "Manual");

// 使用实例
my.CORA_SDK.setPageCollectionMode("AUTO");

Parameter Description:

Field nametypeIs it necessaryexplainillustrate
mode“AUTO” | “Manual”yesHow to collect page events“Manual” Manual “AUTO” Automatic (default mode)

Automatic mode: enabled by default , used with gtp, suitable for general scenarios.

Manual mode: manually turned on, can also be used with gtp, suitable for highly customized scenarios.

4.9 updatePageProperties

Update buried point parameters

After adding buried parameters, all pages will take effect.

To clear the newly added properties, just call the method again and pass in the empty object {}

my.CORA_SDK.updatePageProperties({
   "key1": value1,
   "key2": value2,
   "key3": value3,
   ...
});
Field nametypeIs it necessaryexplain
pageParamsObjectnoAdd buried parameters to the current page

4.10 updatePageName

Update page name

// my.CORA_SDK.updatePageName(pageName:string)
my.CORA_SDK.updatePageName("homePage");
Field nametypeIs it necessaryexplain
pageNamestringyesChange current page name

4.11 setPlatform

Set up the device system, instructions for use:

Field nametypeIs it necessaryexplain
platformstringyesDevice system: iOS, Android, Windows Mobile, PC, H5, MiniApp
// 举例:小程序端打开外部链接,跳转落地页后调用此方法
my.CORA_SDK.setPlatform("MiniApp")


4.12 setPageLoadOptions

Set page path parameters, instructions for use:

Field nametypeIs it necessaryexplain
optionsobjectyesPage path parameters
// 举例:setPageLoadOptions
Page({
     onLoad(options) {
         my.CORA_SDK.setPageLoadOptions(options)
     }
 })


4.13 getGtpInfo (abandon)

To get the complete gtp parameters, use: my.CORA_SDK.getGtpInfo(‘a.b.c.d’);


my.CORA_SDK.getGtpInfo("a.b.c.d") // console.log('a.b.c.d')

4.14 getPageIdInfo

Get the pageId and bring the parameters when the page jumps to H5

// 代码示例:
const coraSourcePageId = my.CORA_SDK.getPageIdInfo()

4.15 getDeviceId

Get the deviceId and bring the parameters when the page jumps to H5

// 代码示例:
const coraSourceDeviceId = my.CORA_SDK.getDeviceId()

4.16 getJumpH5Params

Get complete jump H5 parameters 
Field nametypeIs it necessaryexplain
gtpstringNgtp information of the block a.b.c.d
// 示例
const jumpH5Params = my.CORA_SDK.getJumpH5Params('a.b.c.d')

console.log(jumpH5Params) 
// 得到coraSourceAppId=123&coraSourceGtp=a.b.c.d&coraSourcePageId=1&coraSourceDeviceId=deviceId

4.17 getAllUrlParams

Gets the full url parameters

in parameter:

字段名类型是否必须解释
optionsobjectonLoad(options) {
const getAllUrlParams = my.CORA_SDK.getAllUrlParams(options)
}

代码示例:
onLoad(options) {
// onLoad options
const getAllUrlParams = my.CORA_SDK.getAllUrlParams(options)
// console gtp=appId.pagehome.c.d&id=1
}

4.18 GTX

  1. Introduction to GTX automatic point burying
    • GTX buried points are used to track and analyze page traffic, and can solve the following key business problems:
      • Statistics of basic indicators such as PV and UV of the specified page;
      • Track the source and destination of page traffic and analyze the traffic funnel of user paths;
      • Based on traffic and conversion evaluation, inform the business side of the traffic efficiency of each page and the pit within the page;
    • Glossary:
      • Global Tracking Position (GTP): Global position tracking model, used to track locations and the flow of traffic between different locations;
      • Global Tracking Content (GTC): Global content tracking model, used to track delivery content and guide conversion efficiency;
      • Global Tracking X (GTX): refers to the solution composed of GTP and GTC;
  2. GTP buried point
    • GTP parameter definition: a.b.c.d = ${appId}.${pageId}.${module}.${point}, GTP needs to be constructed and used strictly in accordance with the following specifications. The UI layer constructs the four-layer structure through structured data (this method is recommended), or it can be constructed manually.
GTPmeaningillustrate
a position${appId}Globally unique, allocated independently on different ends, such as: c120420
b position${page}The b bit is automatically generated based on the URL of the page.
c position${module}The floor or module number of the page
d position${component}Subdivided submodule number

[Important] class=”data-gtp” data-gtp=”abcd” must be in the last node

Code example:

<!-- Good case class="data-gtp" data-gtp="c.d" 必须在末尾节点中 -->
<view>
    <view class="data-gtp" data-gtp="c.d">
        正常点击、曝光
    </view>
</view>

<!-- Bad case -->
<view>
    <view class="data-gtp" data-gtp="c.d">
        正常点击、曝光
        <view>末尾节点 还有节点</view>
    </view>
</view>

To jump between internal pages of the mini program, if you use code to jump to the url, you need to add &coraGtp=a.b.c.d

// html
<view class="data-gtp" data-gtp="{{gtpValue}}" onTap="handleGo">
      Normal click, exposure
</view>

// JS:
// 配合 4.12 setPageLoadOptions 使用
Page({
     onLoad(options) {
         my.CORA_SDK.setPageLoadOptions(options)
     },
     handleGo(e) {
         my.navigateTo({
             url: /pages/index?coraGtp=${e.currentTarget.dataset.gtp}
         });
     }
 })

When jumping out of the mini program to H5, the URL needs to have parameters.

https://xxx.com?`${my.CORA_SDK.getJumpH5Params()}`

Other uses of GTP buried points

DOM propertiesillustrate
data-gtp-only-clickclick only
data-gtp-only-exposeExposure only
data-gtp-multiclickSupport multiple clicks to bury points

代码示例


<!-- Good case -->
<view>
    <view class="data-gtp" data-gtp="c.d" data-gtp-only-click="true">
        只点击
    </view>
    <view class="data-gtp" data-gtp="c.d" data-gtp-only-expose="true">
        只曝光
    </view>
    <view class="data-gtp" data-gtp="c.d" data-gtp-multiclick="true">
        支持多次点击
    </view>
</view>


<!-- Bad case -->
<view>
     <view class="data-gtp" data-gtp="c.d" data-gtp-only-click="true">
        只点击
        <view>末尾节点 还有节点</view>
    </view>
</view>

页面跳转示例,需要url传参 &gtp=`c.d`:

// Used with 4.12 setPageLoadOptions
Page({
     onLoad(options) {
         my.CORA_SDK.setPageLoadOptions(options)
     }
 })

3. GTC burying point

  • GTC parameter definition: a.b.c.d = ${sysId}.${algoId}.${algoVer}.${audienceId}, GTC also contains a 4-layer structure, definitions at different levels
GTCmeaningillustrate
a position${sysId}Delivery system ID, used to identify different content delivery parties
b position${algoId}Delivery algorithm ID, used to identify the delivery algorithm used by the delivery system to generate different content
c position${algoVer}Delivery algorithm version ID, used to identify different versions of the delivery algorithm
d position${audienceId}The placement group ID is used to identify different placement groups.
页面跳转示例,需要url传参 &gtc=a.b.c.d:
// 配合 4.12 setPageLoadOptions 使用
Page({
     onLoad(options) {
         my.CORA_SDK.setPageLoadOptions(options)
     }
 })

4.19 Get AB Test experimental parameter

  1. getBucket

This method is used to obtain the experimental bucket corresponding to the experiment

Input instructions:

Field nametypeIs it necessaryexplainillustrate
experimentstringyueExperiment name

Request code example:

my.CORA_SDK.abTest.getBucket("xxx_layer").then((res) => {
    console.log(res) // { bucket:"xxx"}
})

Parameter description:

Field nametypeIs it necessaryexplainillustrate
bucketstringnoExperiment bucketWhen the incoming experiment name does not exist, an empty object is returned.

Request code example:

{
    bucket:"xxx"
}
  1. getBucketObject
This method is used to obtain the experimental bucket corresponding to the experiment (more complete data)
Input instructions:
Field nametypeIs it necessaryexplainillustrate
experimentstringyesExperiment nameWhen the incoming experiment name does not exist, an empty object is returned.

Request code example:

my.CORA_SDK.abTest.getBucketObject("xxx_layer").then((res) => {
    console.log(res)
})

Parameter description:

Field nametypeIs it necessaryexplainillustrate
namestringExperiment name
versionstringExperiment version
bucketstringExperiment bucket name
bucketVersionstringExperiment bucket version

Request code example:

{
    "name": "sean_test01",
    "version": "11"
    "bucket": "base",
    "bucketVersion": "11",
}

5. Information collection form

Field nametypeIs it necessarydefault valueexplain
// Event
eventTypestringyes“CUSTOM”CLICK click event EXPOSE exposure event PAGE page event CUSTOM custom event
eventNamestringyes“”event name
eventTimestringyes“”Client reporting time
eventValue {object} Basic information of buried points: event value
Call external incoming
eventProps {object} basic information: SDK built-in event value
customDeviceIdstringno“”Custom device Id calls 4.7 function my.CORA_SDK.setCustomDeviceId(“xxid”)
pageNamestringno“”The page name calls the 4.10 function my.CORA_SDK.updatePageName(pageName:string). The function is not called: the page name is automatically generated.
isbfstringyes“0”Browser or tab switching hides “0” and the default value “1” indicates switching.
isbstringyes“0”The page exposure caused by clicking the browser’s back button is “0” and the default value “1” means going back.
startTimestringnoPage visit start time
endTimestringnoPage visit end time
pageDurationstringnoTime on page
referPagestringno“xx”Previous page URL
gtpstringyes“”gtp data
gtpPre1stringyes“”Previous page gtp data
gtpPre2stringyes“”Previous page gtp data
gtcPre1stringyes“”Previous page gtc data
gtcPre2stringyes“”Previous page gtc data
sdkInitDatestringyes“”SDK buried information: first call time
enabledTrackingbooleanyesfalseAdvertisement push
enabledNotificationbooleanyesfalseAdvertisement push permission
platformstringyes“”Platform: Windows | Mac | Linux | Android | iOS
containerstringyes“”Container: NONE | BROWSER | APP | MINIAPP
juststringyes“”Device information: language
uidstringyes“”User information: user id
deviceIdstringyes“”device id
browserstringyes“”Browser
browserVersionstringyes“”Browser model
systemNamestringyes“”operating system
systemVersionstringyes“”Operating system version
sdkVersionstringyes“”SDK version
userAgentstringyes“”ua information
deviceScreenXpxnumberyesDevice hardware information: Device screen resolution Xpx
deviceScreenYpxnumberyesDevice hardware information: Device screen resolution Ypx
deviceScreenOrientstringyesDevice hardware information: device screen orientation
deviceScreenIsTouchbooleanyesfalseDevice hardware information: whether the device screen can be touched
deviceBatteryLevelnumberyesEquipment hardware information: battery level
deviceBrandstringyesEquipment brand
deviceNetworkstringyesDevice network information: WIFI 3G 4G 5G
Share to
1
1 Likes
Prev page

Recomm

Comments (0)

Contact