gravity_engine_flutter_sdk #

GravityEngineSDK for flutter.

引用 #

项目引用 #

项目pubspec.yaml文件中引用SDK

dependencies:
  gravity_engine_flutter_sdk: ^1.0.3

代码引用 #

在调用类引用SDK

import 'package:gravity_engine_flutter_sdk/GravityEngineSDK.dart';

SDK功能支持 #

SDK定义的枚举 #

部分方法需要传入定义的枚举

//自动收集事件类型

enum AUTO_TRACK_EVENTS {
  NONE,//不触发上报
  APP_START, // 当应用进入前台的时候触发上报，对应 $AppStart
  APP_END, // 当应用进入后台的时候触发上报，对应 $AppEnd
  APP_CRASH, // 当出现未捕获异常的时候触发上报，对应 $AppCrash
  APP_INSTALL, // 应用安装后首次打开的时候触发上报，对应 $AppInstall
  APP_SCENE_VIEW, // 当应用内加载界面展示时触发上报，对应 $AppView
  APP_SCENE_CLICK, // 当应用内卸载界面点击触发上报，对应 $$ppClick
  APP_ALL, // 默认不再开启crash信息的收集
}

// 数据上报状态
enum GE_TRACK_STATUS {
  PAUSE, // 暂停数据上报
  STOP, // 停止数据上报，并清除缓存
  SAVE_ONLY, // 数据入库，但不上报
  NORMAL, // 恢复数据上报
}

//SDK运行模式
enum SDKRunMode { NORMAL, DEBUG } // 根据需要扩展 SDKRunMode 枚举

SDK定义的初始化回调接口 #

abstract class InitializeCallback {
  /// 初始化成功
  void onSuccess(Map<Object?, Object?>? responseJson);

  /// 初始化失败
  void onFailed(String? errorMsg);
}

SDK具体支持的方法定义 #

手动初始化 Gravity Engine SDK

  /// <param name="accessToken">项目token</param>
  /// <param name="mode">SDK运行模式(可选)（默认为正常模式）</param>
  /// <param name="enableImei">是否采集 imei，仅支持 Android，默认true（选填）</param>
  /// <param name="enableOaid">是否采集 oaid，仅支持 Android，默认true（选填）</param>
  /// <param name="enableAndroidId">是否采集 android_id，仅支持 Android，默认true（选填）</param>
  /// <param name="enableMAC">是否采集 mac，仅支持 Android，默认true（选填）</param>
  static Future<void> startGravityEngine(
    String accessToken, [
    SDKRunMode mode = SDKRunMode.NORMAL,
    bool enableImei = true,
    bool enableOaid = true,
    bool enableAndroidId = true,
    bool enableMAC = true,
  ]);

在引力引擎注册，其他方法均需在本方法回调成功之后才可正常使用（iOS专用）

  /// <param name="enableAsa"></param>                是否开启asa归因
  /// <param name="clientId"></param>                 用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv 作为用户唯一标识（推荐传空字符串）
  /// <param name="caid1MD5"></param>                 当前用户中广协 ID 的 md5 hash（20230330 版本）（可为空）
  /// <param name="caid2MD5"></param>                 当前用户中广协 ID 的 md5 hash（20220111 版本）（可为空）
  /// <param name="enableSyncAttribution"></param>    是否开启同步获取归因信息，具体请参考同步归因：https://doc.gravity-engine.com/turbo-integrated/sync_attribution.html
  /// <param name="channel"></param>                  当前包渠道
  /// <param name="initializeCallback"></param>       网络回调，其他方法均需在回调成功之后才可正常使用
  static Future<void> initializeIOS(
    bool enableAsa,
    String clientId,
    String caid1MD5,
    String caid2MD5,
    bool enableSyncAttribution,
    String channel,
    InitializeCallback initializeCallback,
  );  

在引力引擎初始化，其他方法均需在本方法回调成功之后才可正常使用

  /// <param name="clientId"></param>                 用户唯一标识(如传空，则使用调用StartGravityEngine时传入的clientID；如传，则会使用当前传入的clientID)
  /// <param name="nickname"></param>                 用户昵称
  /// <param name="enableSyncAttribution"></param>    是否开启同步获取归因信息，具体请参考同步归因：https://doc.gravity-engine.com/turbo-integrated/sync_attribution.html
  /// <param name="channel"></param>                  当前包渠道
  /// <param name="initializeCallback"></param>       网络回调，其他方法均需在回调成功之后才可正常使用
  static Future<void> initialize(
    String clientId,
    String nickname,
    bool enableSyncAttribution,
    String channel,
    InitializeCallback initializeCallback,
  );

获取底层SDK版本

  static Future<String?> getPlatformVersion();

开启自动采集功能.

  /// <param name="events">自动采集事件</param>
  /// <param name="properties">自动采集事件扩展属性(可选)</param>
  static Future<void> enableAutoTrack(
    List<AUTO_TRACK_EVENTS> events,
    [Map<String, dynamic>? properties,]
  );

设置自动采集扩展属性.

  /// <param name="events">自动采集事件</param>
  /// <param name="properties">自动采集事件扩展属性</param>
  static Future<void> setAutoTrackProperties(
    List<AUTO_TRACK_EVENTS> events,
    Map<String, dynamic>? properties,
  );

上报付费事件到引力

  /// <param name="payAmount"></param>            付费金额 单位为分
  /// <param name="payType"></param>              付费类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等
  /// <param name="orderId"></param>              订单号
  /// <param name="payReason"></param>            付费原因 例如：购买钻石、办理月卡
  /// <param name="payMethod"></param>            付费方式 例如：支付宝、微信、银联等
  /// return 当前事件的traceId，当使用演练模式时，需要保存下来以供演练模式使用
  static Future<String?> trackPayEvent(
    int payAmount,
    String payType,
    String orderId,
    String payReason,
    String payMethod,
  );

上报原生App广告观看事件 AdShow

  /// <param name="adUnionType"></param>          广告聚合平台类型  （取值为：topon、gromore、admore、self，分别对应Topon、Gromore、Admore、自建聚合）
  /// <param name="adPlacementId"></param>        广告瀑布流ID
  /// <param name="adSourceId"></param>           广告源ID
  /// <param name="adType"></param>               广告类型 （取值为：reward、banner、 native 、interstitial、 splash ，分别对应激励视频广告、横幅广告、信息流广告、插屏广告、开屏广告）
  /// <param name="adnType"></param>              广告平台类型（取值为：csj、gdt、ks、 mint 、baidu，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟）
  /// <param name="ecpm"></param>                 预估ECPM价格（单位为元）
  static Future<void> trackAdShowEvent(
    String adUnionType,
    String adPlacementId,
    String adSourceId,
    String adType,
    String adnType,
    double ecpm,
  );

上报提现事件到引力

  /// <param name="payAmount"></param>            提现金额 单位为分
  /// <param name="payType"></param>              货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等
  /// <param name="orderId"></param>              订单号
  /// <param name="payReason"></param>            提现原因 例如：用户首次提现、用户抽奖提现
  /// <param name="payMethod"></param>            提现支付方式 例如：支付宝、微信、银联等
  static Future<void> trackWithdrawEvent(
    int payAmount,
    String withPayType,
    String withOrderId,
    String payReason,
    String payMethod,
  );

上报业务注册事件

  static Future<void> trackRegisterEvent();

主动触发上报缓存事件到服务器.

  static Future<void> flush();

设置公共事件属性. 公共事件属性指的就是每个事件都会带有的属性.

  /// <param name="superProperties">公共事件属性</param>
  static Future<void> setSuperProperties(Map<String, dynamic>? properties);

删除某个公共事件属性.

  /// <param name="property">属性名称</param>
  static Future<void> unsetSuperProperty(String properties);

返回当前公共事件属性.

  /// return 公共事件属性
  static Future<Map<Object?, Object?>?> getSuperProperties();

返回当前预置事件属性.

  /// returns 预置事件属性
  static Future<Map<Object?, Object?>?> getCurrentPresetProperties();

清空公共事件属性.

  static Future<void> clearSuperProperties();

track 事件及事件属性，并指定 $event_time #zone_offset 属性. 该事件会先缓存在本地，达到触发上报条件或者主动调用 Flush 时会上报到服务器.

  /// <param name="eventName">事件名称</param>
  /// <param name="properties">事件属性</param>
  static Future<void> track(
    String eventName,
    Map<String, dynamic>? properties,
  );

记录事件时长. 调用 TimeEvent 为某事件开始计时，当 track 传该事件时，SDK 会在在事件属性中加入 #duration 这一属性来表示事件时长，单位为秒.

  /// <param name="eventName">事件名称</param>
  static Future<void> timeEvent(String eventName);

设置用户属性. 该接口上传的属性将会覆盖原有的属性值.

  /// <param name="properties">用户属性</param>
  /// <param name="dateTime">用户属性设置的时间(可选)</param>
  static Future<void> userSet(
    Map<String, dynamic> properties, [
    DateTime? dateTime,
  ]);

重置一组用户属性

  /// <param name="properties">用户属性列表</param>
  static Future<void> userUnset(List<String> properties);

设置用户属性. 当该属性之前已经有值的时候，将会忽略这条信息.

  /// <param name="properties">用户属性</param>
  /// <param name="dateTime">操作时间(可选)</param>
  static Future<void> userSetOnce(
    Map<String, dynamic> properties, [
    DateTime? dateTime,
  ]);

对数值类用户属性进行累加. 如果属性还未被设置，则会赋值 0 后再进行计算.

  /// <param name="properties">用户属性</param>
  /// <param name="dateTime">操作时间(可选)</param>
  static Future<void> userAdd(
    Map<String, dynamic> properties, [
    DateTime? dateTime,
  ]);

对数值类用户属性进行累加. 如果该属性还未被设置，则会赋值 0 后再进行计算.

  /// <param name="property">属性名称</param>
  /// <param name="value">数值</param>
  static Future<void> userAddOne(String property, dynamic value);

对数值类用户属性取最小值. 如果属性还未被设置，则会赋值 0 后再进行计算.

  /// <param name="properties">用户属性</param>
  /// <param name="dateTime">操作时间(可选)</param>
  static Future<void> userNumberMin(
    Map<String, dynamic> properties, [
    DateTime? dateTime,
  ]);

对数值类用户属性取最大值. 如果属性还未被设置，则会赋值 0 后再进行计算.

  /// <param name="properties">用户属性</param>
  /// <param name="dateTime">操作时间(可选)</param>
  static Future<void> userNumberMax(
    Map<String, dynamic> properties, [
    DateTime? dateTime,
  ]);

对 List 类型的用户属性进行追加，并指定操作时间

  /// <param name="properties">用户属性</param>
  /// <param name="dateTime">操作时间(可选)</param>
  static Future<void> userAppend(
    Map<String, dynamic> properties, [
    DateTime? dateTime,
  ]);

对 List 类型的用户属性进行去重追加，并指定操作时间

  /// <param name="properties">用户属性</param>
  /// <param name="dateTime">操作时间(可选)</param>
  static Future<void> userUniqAppend(
    Map<String, dynamic> properties, [
    DateTime? dateTime,
  ]);

删除用户数据. 之后再查询该名用户的用户属性，将为空字典，但该用户产生的事件仍然可以被查询到

  /// <param name="dateTime">操作时间(可选)</param>
  static Future<void> userDelete([DateTime? dateTime]);

获取设备标识

  /// return The device identifier.
  static Future<String?> getDeviceId();

Gets the client identifier.

  /// return  The client identifier.
  static Future<String?> getCurrentClientID();

设置数据上报状态

  /// <param name="status">上报状态，详见 GE_TRACK_STATUS 定义</param>
  static Future<void> setTrackStatus(GE_TRACK_STATUS status);

传入时间戳校准 SDK 时间.

  /// <param name="timestamp">当前 Unix timestamp, 单位 毫秒</param>
  static Future<void> calibrateTime(Long timestamp);

传入 NTP Server 地址校准 SDK 时间.

  /// 您可以根据您用户所在地传入访问速度较快的 NTP Server 地址, 例如 time.asia.apple.com
  /// SDK 默认情况下会等待 3 秒，去获取时间偏移数据，并用该偏移校准之后的数据.
  /// 如果在 3 秒内未因网络原因未获得正确的时间偏移，本次应用运行期间将不会再校准时间.
  /// <param name="timestamp">可用的 NTP 服务器地址</param>
  static Future<void> calibrateTimeWithNtp(String ntpServer);

绑定数数账号

  /// <param name="taAccountId">当前用户的数数账户 ID (#account_id)</param>
  /// <param name="taDistinctId">当前用户的数数访客 ID (#distinct_id)</param>
  static Future<void> bindTAThirdPlatform(String taAccountId, String taDistinctId);