菜单

Laya快速集成

本文档主要讲述 Laya 接入 引力引擎 的技术接入方案，在开始接入前，建议您先阅读 接入前准备以了解接入必备的基础概念。

本接入方案仅适用于Laya开发的项目。如果您使用的是其他开发框架，请访问引力引擎SDK总览页面选择对应的框架接入文档。

支持平台

  • 微信小游戏
  • 快手小游戏（打包成微小）
  • 抖音/Tiktok小游戏
  • 支付宝小游戏
  • OPPO快游戏
  • VIVO快游戏
  • 华为快游戏
  • 小米快游戏
  • 百度小游戏
  • 淘宝小游戏
  • Bilibili 小游戏
  • 京东小游戏（打包成微小）
  •  美团小游戏（打包成微小）
  • Android
  • iOS

媒体平台SDK集成说明​​

​​🎯 集成策略说明：​​

Laya SDK ​​仅针对【微信小游戏】平台​​ 集成了腾讯广告小游戏SDK。对于Laya项目发布至其他平台（如抖音小游戏、快手小游戏等），​​我们未集成任何媒体的SDK​​。

​微信小游戏平台 ✅​​

  • ​​状态​​：已集成腾讯广告小游戏SDK

  • ​​上报方式​​：需​​手动调用​​我们提供的方法进行事件上报

  • ​​版本​​：自 4.8.40开始支持

 
📌 重要说明
引力SDK会自动上报以下两个基础事件给腾讯：
  • REGISTER（用户注册）
  • RE_ACTIVE（沉默唤起）

此外，START_APP（小游戏启动）事件由腾讯SDK自动采集（引力SDK初始化腾讯SDK时默认开启该功能）。

除以上事件外，其他所有事件（如付费、自定义行为等）均需客户端手动调用我们提供的方法进行上报。

点击查看详细集成文档：‍‌​​‬​‬​​​​​​⁠​​​‌‍​​​​‬‬​​‬⁠‌​​⁠⁠​‬引力&腾讯广告小游戏 SDK 接入指南

1. 获取 AccessToken

您可以在设置-应用管理页面点击 查看参数 按钮获取当前应用的 AccessToken ，请妥善保存避免泄露。

2.Native平台支持

Android

1.接入 Android SDK

在Laya导出的Android项目里，集成Android版本的GravityengineSDK即可，参考Android接入文档
 

iOS

1.导入通道文件

将下载的layasdk/native/iOS下的GravityEngineCocosCreatorChannel.h和GravityEngineCocosCreatorChannel.mm 类文件引入到cocos导出的iOS项目下

2.接入 iOS SDK

在Laya导出的iOS项目里集成iOS版本的GravityengineSDK，参考iOS接入文档
 

3.配置并启动 SDK

开始接入工作之前，您需要先下载 SDK

从 ge_laya_sdk_version.zip 中导入 SDK：

TypeScript 项目
  • 将声明文件 GravityAnalyticsSDK.d.ts 放入 libs目录；
  • 将 SDK 文件 gravityengine.mg.layats.min.js 放入 bin/js 目录中
  • 修改 bin/index.js 文件，加载 SDK：
// sdk必须在bundle.js之前加载
loadLib("js/gravityengine.mg.layats.min.js");
loadLib("js/bundle.js");
JavaScript 项目
  • 将 gravityengine.mg.laya.min.js 导入工程：
import GravityAnalyticsAPI from "gravityengine.mg.laya.min.js";

引入 SDK 后，即可进行 SDK 初始化参数配置：

import GravityAnalyticsAPI from "./gravityengine.mg.cocoscreator.min.js"; // cocos2.x项目可能不需要引入
const config = {
    accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
    clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
    name: "ge", // 全局变量名称
    enableNative: false, //是否支持Native
    //Native配置
    mClientIdPriorityOrder: ["OAID","ANDROID_ID"],//Android设备clientID优先级顺序，默认优先取 OAID 为clientId
    foregroundSessionThreshold:0,//前台会话阀值
    enableAndroidId:true,// 是否采集android_id，仅支持Android，默认true
    enableOAID:true, // 是否采集oaid，仅支持Android，默认true
    enableIMEI:true,// 是否采集imei，仅支持Android，默认true
    enableMAC:true, // 是否采集mac，仅支持Android，默认true
}
const ge = new GravityAnalyticsAPI(config);
ge.setupAndStart();

配置项目合法域名：您需要将 https://backend.gravity-engine.com 和 https://api.gravity-engine.com 配置到开发者后台 request 合法域名列表中。

如果您是从低版本（5.0 以下版本）引力 sdk 升级到高版本的，请一定记得添加https://api.gravity-engine.com域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！

4.初始化

在用户可以获取到用户唯一 ID时调用此方法，推荐首次启动时调用。

首次调用后，需要在 initialize的 then中才能继续调用其他事件上报的方法

初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）

方法示例

ge.initialize({
  name: "your_name",
  version: 123,
  openid: "your_openid",
  enable_sync_attribution: false,
})
  .then((res) => {
    console.log("initialize success", res);
  })
  .catch((err) => {
    console.log("initialize failed", err);
  });

参数说明

参数名称 参数含义 参数类型 是否必传
name 用户名或用户唯一ID（可理解为业务中的昵称），如果不需要昵称，可以填：默认值，但是不可以传空字符串！ string 是
version 产品发布版本号，便于后续在引力后台过滤 number 是
openid 用户openid string 是
enable_sync_attribution 是否开启同步获取归因信息（参考同步归因文档） boolean 是
channel 当前用户来源渠道，对应用户细查中的：客户端渠道 string 否

5.事件上报

5.1 业务注册事件上报

此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。

该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）

当用户完成应用内业务注册后，您可以调用 registerEvent 方法来上报用户注册事件($MPRegister)给引力，引力会使用该事件统计指标：标准_注册数

调用示例

ge.registerEvent();

5.2 付费事件上报

付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。

如果您需要通过后端 API 方式上报付费事件，请参考 混合上报模式 来接入事件上报接口报送付费事件。

当用户发生付费行为时，需要调用 payEvent 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！

方法示例

ge.payEvent(payAmount, payType, orderId, payReason, payMethod);

参数说明

参数名称 参数含义 参数类型 是否必传
payAmount 付费金额 单位为分。请务必注意，传错单位可能会导致买量受到影响！ number 是
payType 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：国际标准组织 ISO 4217 代码表 string 是
orderId 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ string 是
payReason 付费原因 例如：购买钻石、办理月卡 string 是
payMethod 付费方式 例如：支付宝、微信、银联等 string 是

调用示例

ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");

5.3 广告观看事件上报

广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。

抖音小游戏、快手小游戏、B站小游戏无需接入，会由引力后端自动拉取，具体配置，请参考这里

为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。

我们为您准备了详细的指引：​​ ​​👉 广告聚合平台字段配置说明

若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：

Native调用方法示例

nativeAdShowEvent(adUnionType, adPlacementId, adSourceId,adType,adnType,ecpm)

参数说明

参数名称 参数含义 参数类型 是否必传
adUnionType 广告聚合平台类型（取值为：topon、gromore、admore、self，分别对应Topon、Gromore、Admore、自建聚合） string 否
adPlacementId 广告瀑布流ID（广告位ID） string 否
adSourceId 广告源ID（代码位ID） string 否
adType 广告类型 （取值为：reward(激励视频广告)、banner(横幅广告)、 native(信息流广告)、interstitial(插屏广告)、 splash(开屏广告) 、video_feed(视频信息流)、
video_begin(贴片广告)）
 string 是
adnType 广告平台类型（取值为：csj、gdt、ks、 mint 、baidu，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟） string 否
ecpm 预估ECPM价格（千次展示收入（单位元）） float 建议填写

小游戏调用方法示例

miniGameAdShowEvent(ad_type, ad_unit_id, otherProperties)

参数说明

参数名称 参数含义 参数类型 是否必传
adType 广告类型 （取值为：reward(激励视频广告)、banner(横幅广告)、 native(信息流广告)、interstitial(插屏广告)、 splash(开屏广告) 、video_feed(视频信息流)、
video_begin(贴片广告)）
 string 是
adUnitId 广告位ID。一般以adunit开头，注意不要填错 string 是
otherProperties 自定义参数。其他需要携带的自定义参数，需要提前在引力后台元数据管理中针对广告观看($AdShow) 事件配置好相关属性 object 是

6.接入验证

正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！

6.1 关键事件验证

在引力后台事件流 界面开启加载实时数据，并在产品中触发以下几个事件。事件流使用说明：‬⁠​​⁠​‬‌‌‍‍⁠⁠⁠⁠‍​​​​​​​​⁠‬‍⁠‍‌​⁠​​⁠⁠​‬​‬​​事件流 - 飞书云文档

事件名 事件英文名 触发时机 采集方式 默认映射到媒体事件 备注
用户注册

$MPRegister

 用户完成业务注册之后 调用SDK的上报业务注册事件方法采集 暂无 接入了业务注册上报事件的产品均需要校验
付费 $PayEvent 用户付费之后 调用SDK的上报用户付费事件方法采集 付费 接入了付费事件上报事件的产品均需要校验
广告展示 $AdShow 用户观看广告之后 调用SDK的上报广告展示事件方法采集 暂无 接入了广告事件上报事件的产品均需要校验

触发操作后，请在事件流 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。

6.2 避免重复上报

如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！

至此验证无误之后，您可以正常上线了。

 

 

 

 

 

上一个
Laya
下一个
行为事件上报
最近修改: 2026-02-09Powered by