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

Coraool WebSDK 开发指南

1. 介绍

Coraool WebSDK集成了埋点系统 & API调用系统。

2. 对接流程

整体流程说明:

  • STEP1:开发者接入Coraool WEBSDK,调用自定义埋点上报
    • 1. 初始化
    • 2. 设置登录态
    • 3. 自定义埋点
  • STEP2:调用 API 获取数据,获取数据。

3.使用说明

3.1 script 引入方案

<script src="https://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-web-sdk-1.0.4-beta.js"></script>
VersionDateRelease NotesSDK
20240318稳定版
1、提高了invoke数据的实时性
2、深度优化并增强了数据上报的稳定性和兼容性
https://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-web-sdk-1.1.0.js
20240424新稳定版
1、增加了用户路径追踪
https://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-web-sdk-2.1.0.js
20240524新稳定版
1. 更新GTP统计方式,支持一个URL中多个PAGE事件
https://digiplus.coraoolstatic.com/com.coraool.digiplus/coraool-web-sdk-2.1.2.js

  3.2 调用示例

1. 步骤一:初始化

window.CORA_SDK.initialize({
    AppId: "appId", // 目前传测试值,后续在coraool申请
    AppKey: "appKey",
    AppSec: "appSec",
})

2. 步骤二:设置登录态

设置登录态(登录,登出时调用)

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

3. 步骤三:API调用示例

  1. Invoke 方法调用

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

2. Track埋点

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

4. API说明

4.1 initialize

    SDK初始化,入参说明:

字段名类型是否必须解释说明
AppIdstringSDK初始化参数的AppId业务方接入SDK时分配,不同端独立分配,全局唯一
AppKeystring唯一应用标识业务方接入SDK时分配,每个端一个
AppSecstring数据交互的加密串业务方接入SDK时分配,每个端一个

  示例:

window.CORA_SDK.initialize({
    AppId: "appId", // 目前传测试值,后续在coraool申请
    AppKey: "appKey",
    AppSec: "appSec",
})

4.2 setUserId

    设置userId 、afId,入参说明:

字段名类型是否必须解释
userIdstring用户的userId,未登录时传空字符串
afIdstring用户的afId,获取不到afId时传空字符串

示例:

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

4.3 Invoke

调用api

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

  入参说明:

字段名类型是否必须解释
apiNamestringapi的名字例:获取Ranking列表数据:apiName: “bingoplus.home.game.ranking”
apiVersionstring不传时默认1.0.0版本

 出参说明:

{
    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 // 实验参数,用于埋点上报
    }
}

  出参说明:

字段名类型解释
Objectranking列表返回的结果
versionstring版本号
rankingArray排序数据
gameIdstring游戏Id
platformIdstring游戏厅Id
gameTopstring | null游戏排行
gameTypenumber游戏类型
likeCntnumber| null收藏数
tagsstring[] | null推荐标签,
track埋点数据
expLayerstring实验参数,用于埋点上报
用户新老用户标识 NEWUSER(新用户) / OLDUSER(老用户) / BASE(如果userId和设备id都不传会返回BASE)
expBucketstring实验参数,用于埋点上报
expAlgstring实验参数,用于埋点上报
expExtrastring | null扩展参数,用于埋点上报

4.4 Track

自定义埋点

自定义埋点的应用场景非常广泛,需要灵活运用,避免数据多报,误报。

window.CORA_SDK.track("eventName", {
    pageName: "homePage", // 页面名称
    eventType: "PAGE", // CLICK 点击 EXPOSE曝光 PAGE页面 CUSTOM自定义(不填为自定义)
    customClickKey1: "customClickValue1",
    customClickKey2: "customClickValue2",
    customClickKey3: "customClickValue3",
});
字段名类型是否必需解释
eventNamestring事件名(规范填写)
eventValueParamsObject事件对象
字段名类型是否必需解释
pageNamestring页面名称
eventTypestringCLICK点击、EXPOSE曝光、PAGE页面、CUSTOM自定义事件不填/空 自定义事件
customxxxstring自定义key value

4.5 trackPageStart

进入页面埋点,若埋点方式为手动模式,可自行开始埋点。

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

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

参数说明:

字段名类型是否必需解释
eventNamestring事件名字
eventValueObject事件对象

4.6 trackPageEnd

离开页面埋点,离开页面的埋点(和 trackPageStart 配合使用,参数一致)

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

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

4.7 setCustomDeviceId

支持自定义设备ID

window.CORA_SDK.setCustomDeviceId("xxid");

4.8 setPageCollectionMode

设置埋点模式,支持两种埋点模式:手动、自动。



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

参数说明:

字段名类型是否必需解释说明
mode“AUTO” | “MANUAL”页面事件的采集方式“Manual” 手动 “AUTO” 自动(默认方式)

自动模式:默认开启,自动上报页面埋点。

手动模式:手动开启,关闭页面自动上报。

4.9 updatePageProperties

更新埋点参数

添加埋点参数后所有页面都会生效

若要清空新增的属性,只需再调用一次方法,传入空对象{}

window.CORA_SDK.updatePageProperties({
   "key1": value1,
   "key2": value2,
   "key3": value3,
   ...
});
字段名类型是否必需解释
pageParamsObject为当前页面添加埋点的参数

4.10 updatePageName

更新页面名称

// window.CORA_SDK.updatePageName(pageName:string)
window.CORA_SDK.updatePageName("homePage");
字段名类型是否必需解释
pageNamestring更改当前页面名称

4.11 setPlatform

设置设备系统,使用说明:

字段名类型是否必须解释
platformstring设备系统:iOS、Android、Windows Mobile、PC、H5、MiniApp
// 举例:小程序端打开外部链接,跳转落地页后调用此方法
window.CORA_SDK.setPlatform("MiniApp")

4.12 setAutoPageTrack

页面自动上报,使用说明:

// 和4.8 window.CORA_SDK.setPageCollectionMode("MANUAL")配合使用
window.CORA_SDK.setAutoPageTrack()

// 此方法可以写到全局的路由守卫中,如果没有其他PAGE_xx事件,则使用用此方法发送自动上报

4.13 getGtpInfo

获取gtp的值

// @params pageName {string} 页面名
// @params cd {string} 4.14GTX章节中c和d的位置,
window.CORA_SDK.getGtpInfo(pageName, cd)

// 放方法示例:
cont gtp = window.CORA_SDK.getGtpInfo('PAGE_HOME', 'Feeds.0')
console.log(gtp) // 输出结果 '123.PAGE_HOME.Feeds.0'

4.14 GTX

  1. GTX 自动化埋点简介
    • GTX埋点用于页面流量的追踪和分析,可以解决如下关键业务问题:
      • 统计指定页面的PV、UV等基础指标;
      • 追踪页面流量的来源和去向,分析用户路径的流量漏斗;
      • 基于流量和转化评估,告知业务方,每个页面以及页面内坑位的流量效率;
    • 名词解释:
      • Global Tracking Position(GTP):全局位置跟踪模型,用于追踪位置以及不同位置之间流量的流转;
      • Global Tracking Content(GTC):全局内容跟踪模型,用于跟踪投放内容以及引导转化效率;
      • Global Tracking X (GTX):指代 GTP、GTC 构成的解决方案;
  2. GTP 埋点
    • GTP参数定义:a.b.c.d = ${appId}.${pageId}.${module}.${point},GTP需要严格按照如下规范进行构造和使用,UI层通过结构化的数据构造这4层结构(建议用这种方式),也可以通过手动的方式构造。
    • 【重要】a标签页面跳转<a href="/页面名?coraGtp=a.b.c.d"></a> ,使用代码跳转url需要加上 &coraGtp=a.b.c.d
GTP含义说明
a位${appId}全局唯一,不同端独立分配,如:c120420
b位${page}b位根据页面的url自动化生成
c位${module}页面的楼层或者模块编号
d位${component}细分的子模块编号

代码示例:

<!-- 页面曝光 -->
<body>
    <div class="xx">
        <!-- 楼层 or 模块 -->
        <div data-gtp-c="floor1xx">
            <div class="xx">
                <div data-gtp-d="1xx">d一号位</div>
                <div data-gtp-d="2xx">d二号位</div>
            </div>
        </div>
        <div class="xx"></div>
        
        <!-- 楼层 or 模块 -->
        <div data-gtp-c="floor2xx">
            <div class="xx">
                <div data-gtp-d="1xx">d一号位</div>
                <div data-gtp-d="2xx">d二号位</div>
            </div>
        </div>
        <div class="xx"></div>
    </div>
</body>

GTX 埋点其他用法

DOM属性说明
data-gtp-ext服务d位的扩展字段属性,该属性值通过JSON.stringify转换
<div data-gtp-d=”LOGIN” data-gtp-ext='{“itemId”:123}’>d位</div>
data-gtp-only-click只点击
data-gtp-only-expose只曝光
data-gtp-multiclick支持多次点击埋点
data-gtp-skip不做任何点击曝光;页面不曝光、不点击 & 子DOM均不曝光

代码示例


<div>
    <div data-gtp-c="c位">
        <div data-gtp-d="game1">正常曝光,点击埋点</div>
        <div data-gtp-d="game1" data-gtp-only-click="true"> 只点击</div>
        <div data-gtp-d="only-expose" data-gtp-only-expose="true"> 只曝光</div>
        <div data-gtp-d="game4-track-multiclick" data-gtp-multiclick="true"> 支持多次点击</div>
    
        <div data-gtp-d="c120420.homepage.module" data-gtp-skip="true">
            这一块的均不曝光
            <div data-gtp-d="only-click" data-gtp-only-click="true"> 1</div>
            <div data-gtp-d="only-expose" data-gtp-only-expose="true">2</div>
            <div data-gtp-d="game4-track-multiclick" data-gtp-multiclick="true"> 3</div>
            <div data-gtp-d="track-skip" data-gtp-skip="true">4</div>
        </div>

    </div>
</div>

3. GTC 埋点

  • GTC参数定义:a.b.c.d = ${sysId}.${algoId}.${algoVer}.${audienceId},GTC也包含4层结构,在不同层级上的定义
GTC含义说明
a位${sysId}投放系统 ID,用来标识不同的内容投放方
b位${algoId}投放算法 ID,用来标识投放系统产生不同内容的投放算法
c位${algoVer}投放算法版本 ID,用来标识投放算法的不同版本
d位${audienceId}投放人群 ID,用来标识不同的投放人群

代码示例

通过url传参带入,如: https://www.coraool.com?gtc=a.b.c.d SDK自动补获

5. 信息采集表

字段名类型是否必需默认值解释
// Event
eventTypestring“CUSTOM”CLICK 点击事件EXPOSE 曝光事件PAGE 页面事件CUSTOM 自定义事件
eventNamestring“”事件名
eventTimestring“”客户端上报时间
eventValue {object} 埋点基础信息:事件value
调用外部传入
eventProps {object} 埋点基础信息:SDK内置事件value
customDeviceIdstring“”自定义设备Id调用4.7函数window.CORA_SDK.setCustomDeviceId(“xxid”)
pageNamestring“”页面名调用4.10函数 window.CORA_SDK.updatePageName(pageName:string)没调用函数:自动生成页面名
isbfstring“0”浏览器或tab切换隐藏”0″默认值”1″表示切换
isbkstring“0”点击浏览器回退按钮导致的页面曝光”0″默认值”1″表示回退
startTimestring页面访问开始时间
endTimestring页面访问结束时间
pageDurationstring页面停留时间
referPagestring“xx”上一个页面URL
gtpstring“”gtp数据
gtpPre1string“”上一个页面gtp数据
gtpPre2string“”上上一个页面gtp数据
gtcPre1string“”上一个页面gtc数据
gtcPre2string“”上上一个页面gtc数据
sdkInitDatestring“”SDK埋点信息:首次调用时间
enabledTrackingbooleanfalse广告推送
enabledNotificationbooleanfalse广告推送权限
platformstring“”平台:Windows | Mac | Linux | Android | iOS
containerstring“”容器:NONE | BROWSER | APP | MINIAPP
langstring“”设备信息:language
uidstring“”用户信息: 用户id
deviceIdstring“”设备id
browserstring“”浏览器
browserVersionstring“”浏览器型号
systemNamestring“”操作系统
systemVersionstring“”操作系统版本
sdkVersionstring“”SDK版本
userAgentstring“”ua信息
deviceScreenXpxnumber设备硬件信息:设备屏幕分辨率 Xpx
deviceScreenYpxnumber设备硬件信息:设备屏幕分辨率 Ypx
deviceScreenOrientstring设备硬件信息:设备屏幕方向
deviceScreenIsTouchbooleanfalse设备硬件信息:设备屏幕是否可以触摸
deviceBatteryLevelnumber备硬件信息:电池电量
deviceNetwork设备网络信息

Not allow to forward/copy without permission:CORAOOL » Coraool WebSDK 开发指南
Share to
0 Likes

Recomm

Comments (0)

Contact us