1. 数据埋点(必接)

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 事件的名称和属性名称是字符串类型，只能以字母开头，可包含字母、数字和下划线 "_"，最大长度为 50 个字符。

1.1 AppsFlyer

目前支持 AppsFlyer 埋点方案。

1.2 Firebase

目前支持 Firebase 埋点方案，接入方式查看【集成 Firebase】文档。如果需要使用Firebase的进阶功能(如：设置用户属性、公共事件属性等)，可以通过以下方法获取Firebase服务并调用对应的方法：

SFFirebaseService firebaseService = SFPlatform.getInstance().getFirebaseService();

1.3 数数

目前支持数数埋点方案。如果需要使用数数的进阶功能(如：设置用户属性、公共事件属性等)，可以通过以下方法获取数数服务并调用对应的方法：

SFTDService tdService = SFPlatform.getInstance().getTDService();

1.4 Sofish

目前支持 Sofish 埋点方案，埋点数据会同步上报 Bigquery。如果需要使用Sofish/Bigquery的进阶功能(如：设置公共事件属性等)，可以通过以下方法获取Sofish服务并调用对应的方法：

SFSofishService sofishService = SFPlatform.getInstance().getSofishService();

1.5 方法说明

• 调用 AppsFlyer、Firebase 或 数数埋点方法，进行数据埋点。游戏行为一般情况下只需要上报至数数平台。

  SFPlatform.getInstance().trackEvent(analyticsType, eventName, params);
  

  analyticsType 可以通过 AnalyticsType 类指定：

  • AnalyticsType.AppsFlyer：AppsFlyer埋点
  • AnalyticsType.Firebase：Firebase埋点
  • AnalyticsType.ThinkingData：数数埋点
  • AnalyticsType.Sofish：Sofish埋点(同步上报Bigquery)

• 调用埋点方法，进行数据埋点，该方法上报所有支持的平台，使用前请和发行方确认。

  SFPlatform.getInstance().trackEvent(eventName, params);
  

• 示例：

  HashMap<String, Object> params = new HashMap<String, Object>();
  params.put("analytics_type", "test");
  SFPlatform.getInstance().trackEvent(AnalyticsType.ThinkingData, "event_test", params);
  

2. 广告 ID(选接)

在游戏中需要获取广告 ID 时调用该方法：

SFPlatform.getInstance().getAdvertisingId();

3. 广告收入统计(必接)

广告收入统计功能集成了Sofish、AppsFlyer、Firebase和数数等多家平台，在游戏中需要上报广告收入数据时调用该方法：

SFAdRevenue adRevenue = new SFAdRevenue.Builder()
        .setPlatform(platform)          // 广告平台，如：AppLovin、AdMob
        .setCountry(country)
        .setAdUnitId(adUnitId)
        .setAdFormat(adFormat)
        .setPlacement(placement)
        .setNetworkName(adNetwork)
        .setRevenue(revenue)
        .setCurrency(currency)
        .build();
SFPlatform.getInstance().trackAdRevenue(adRevenue);

如果接入的是 AdMob 广告平台并且关联了Firebase，每当用户看到广告展示时，Firebase都会自动记录 ad_impression 事件。为了避免广告收入不准确，需要忽略SDK上报数据到Firebase平台，在游戏中需要上报广告收入数据时可以传入需要的数据分析类型，数据分析类型可以传1个或多个，代码示例如下：

SFPlatform.getInstance().trackAdRevenue(adRevenue, AnalyticsType.AppsFlyer, AnalyticsType.Sofish, AnalyticsType.ThinkingData);

[!TIP|labelVisibility:hidden|iconVisibility:hidden] 通过Sofish SDK接入广告时不需要调用该方法，如果是自行接入的广告，则需要主动调用该方法上报广告收入。

4. 查询归因数据(选接)

4.1 监听归因数据

在游戏中需要监听归因数据时可以调用该方法：

SFPlatform.getInstance().addConversionDataListener(new SFConversionDataListener() {
    @Override
    public void onConversionData(SFConversionData data) {
        // 如果需要使用归因数据时还没有接收到回调结果，可以发起主动查询操作
    }
});

4.2 查询归因数据

在游戏中需要查询归因数据时调用该方法：

SFPlatform.getInstance().requestConversionData(new SFRequestResultListener<SFConversionData>() {
    @Override
    public void onSuccess(SFConversionData data) {

    }

    @Override
    public void onFailed(int code, String message) {

    }
});

SFConversionData 数据结构如下：

4.3 媒体来源

常用广告投放渠道的媒体来源和归因标识如下表所示：

5. 其他接口(选接)

5.1 获取 AppsFlyer 属性

SFPlatform.getInstance().getAppsFlyerData();    // 返回结果可能为空，使用时需要进行判空校验

5.2 获取 Firebase 属性

SFPlatform.getInstance().getFirebaseData();    // 返回结果可能为空，使用时需要进行判空校验

5.3 获取数数属性

SFPlatform.getInstance().getThinkingData();    // 返回结果可能为空，使用时需要进行判空校验

6. 注意事项

项目开发中遇到网络请求错误，埋点时最好可以在事件的属性中把网络请求的 Url 和错误信息一起上传，便于后面排查具体问题，示例代码如下：

Map<String, Object> params = new HashMap<String, Object>();
params.put("http_url", http_url);          // 网络请求的Url
params.put("http_result", http_result);    // 网络请求的错误信息
SFPlatform.getInstance().trackEvent("app_http_failed", params, listener);

比如一次重试 3 次全部失败的网络请求，http_result 的数据结构可以使用 List<Map<String, Object>>，数据格式可以参考下面的示例：

[
    {
        "http_code": -1,
        "http_result": "javax.net.ssl.SSLPeerUnverifiedException: Cannot verify hostname: cffile.island.sogamecdn.com",
        "network_type": "4G",
        "http_duration": "274388ms",
        "device_time": "2023-09-25 17:49:04"
    },
    {
        "http_code": -1,
        "http_result": "java.net.SocketTimeoutException: failed to connect to cffile.island.sogamecdn.com/104.18.17.2 (port 80) from /10.123.22.235 (port 41046) after 8000ms",
        "network_type": "WIFI",
        "http_duration": "104179ms",
        "device_time": "2023-09-25 17:50:48"
    },
    {
        "http_code": 500,
        "http_result": "",
        "network_type": "NONE",
        "http_duration": "20ms",
        "device_time": "2023-09-25 17:50:48"
    }
]