AppMetrica

AppMetrica 是一款免费的数据分析工具，可帮助你实时跟踪用户行为并分析移动应用的性能表现。将 AppMetrica 与 Adapty 集成后，你可以更深入地了解订阅数据指标和用户互动情况。

如何设置 AppMetrica 集成

设置 AppMetrica 集成主要分为两个步骤：

在 Adapty 看板中配置集成
在应用代码中设置集成

看板配置

要设置 AppMetrica 集成：

打开 AppMetrica 应用列表
选择你想追踪的应用
进入 Settings > Main，复制 Application ID 和 Post API key

在 Adapty 看板中进入 Integrations > AppMetrica
粘贴你的 AppMetrica 凭据。

事件与标签

Adapty 支持向 AppMetrica 发送三组事件，您可以按需启用相关事件来追踪应用表现。完整的可用事件列表，请参阅事件文档。

Note

AppMetrica 每 4 小时同步一次事件，因此事件出现在您的看板中可能会有延迟。

6ed2d88-CleanShot_2023-08-18_at_14.59.042x.webp

Tip

我们建议使用 Adapty 的默认事件名称以保持一致性，但你也可以根据现有的分析设置自定义这些名称。

收入设置

默认情况下，Adapty 以属性形式将收入数据附加到事件中，这些数据会显示在 AppMetrica 的 Events 报告里。你可以配置收入数据的计算和展示方式：

收入计算方式：选择收入值的计算方式，以匹配您的财务报告需求：
- 总收入：显示扣除任何费用前的总收入，适用于追踪客户实际支付的全部金额
- 扣除应用商店佣金后的收益：显示扣除 App Store/Play Store 费用后的收入，帮助您追踪实际到手收益
- 扣除应用商店佣金及税费后的收益：显示扣除商店费用和适用税费后的净收入，最准确地反映您的实际收益
Report user’s currency：启用后，销售额将以用户本地货币报告，便于按地区分析收入。禁用后，所有销售额将统一换算为美元，以便跨市场进行一致的数据统计。
Send revenue events：启用此选项后，收入数据不仅会出现在 Events 报告中，还会出现在 AppMetrica 的 In-app and ad revenue 报告中。请确保不要从其他地方重复发送收入数据，否则可能导致数据重复。
Exclude historical events：启用后，Adapty 不会发送用户在安装含有 Adapty SDK 的应用之前发生的事件。如果你在接入 Adapty 之前已经在向分析平台发送事件，此选项有助于避免数据重复。

SDK 配置

要在您的应用中启用 AppMetrica 集成，需要设置两个标识符：

appmetrica_device_id：基本集成所必需
appmetrica_profile_id：可选，但如果您的应用有用户注册功能，建议设置

使用 setIntegrationIdentifier() 方法来设置这些值。以下是各平台的实现方式：

Note

第三方 SDK 会异步生成用户 ID，在 Adapty.activate() 执行时该 ID 可能尚未就绪。如果你的 Customer User ID 来自此类 SDK，请先不带该 ID 调用 Adapty.activate()。待 ID 到位后，依次调用 setIntegrationIdentifier()，再用 CUID 调用 identify()。

设置 appmetrica_device_id

AppMetrica.requestStartupIdentifiers(on: nil) { ids, error in
  if let error {
    // handle AppMetrica error    
    return
  }

  guard let deviceIDHash = ids?[.deviceIDHashKey] as? String else {
    // handle AppMetrica error
    return
  }

  Task {
    do {
      try await Adapty.setIntegrationIdentifier(
        key: "appmetrica_device_id",
        value: deviceIDHash
      )
    } catch {
      // handle the error
    }
  }
}

设置 appmetrica_profile_id

do {
  try await Adapty.setIntegrationIdentifier(
    key: "appmetrica_profile_id",
    value: "YOUR_APPMETRICA_PROFILE_ID"
  )
} catch {
  // handle the error
}

设置 appmetrica_device_id

val startupParamsCallback = object: StartupParamsCallback {
    override fun onReceive(result: StartupParamsCallback.Result?) {
        val deviceIdHash = result?.deviceIdHash ?: return

        Adapty.setIntegrationIdentifier("appmetrica_device_id", deviceIdHash) { error ->
            if (error != null) {
                // handle the error
            }
        }
    }

    override fun onRequestError(
        reason: StartupParamsCallback.Reason,
        result: StartupParamsCallback.Result?
    ) {
        //handle the error
    }
}

AppMetrica.requestStartupParams(context, startupParamsCallback, listOf(StartupParamsCallback.APPMETRICA_DEVICE_ID_HASH))

设置 appmetrica_profile_id

val startupParamsCallback = object: StartupParamsCallback {
    override fun onReceive(result: StartupParamsCallback.Result?) {
        val deviceIdHash = result?.deviceIdHash ?: return

        Adapty.setIntegrationIdentifier("appmetrica_device_id", deviceIdHash) { error ->
            if (error != null) {
                // handle the error
            }
        }
        
        Adapty.setIntegrationIdentifier("appmetrica_profile_id", "YOUR_ADAPTY_CUSTOMER_USER_ID") { error ->
            if (error != null) {
                // handle the error
            }
        }
    }

    override fun onRequestError(
        reason: StartupParamsCallback.Reason,
        result: StartupParamsCallback.Result?
    ) {
        //handle the error
    }
}

AppMetrica.requestStartupParams(context, startupParamsCallback, listOf(StartupParamsCallback.APPMETRICA_DEVICE_ID_HASH))

设置 appmetrica_device_id


final startupParams = await AppMetrica.requestStartupParams([AppMetricaStartupParams.deviceIdHashKey]);
final deviceIdHash = startupParams.result?.deviceIdHash;

if (deviceIdHash != null) {
  try {
    await Adapty().setIntegrationIdentifier(
        key: "appmetrica_device_id", 
        value: deviceIdHash,
    );
  } on AdaptyError catch (adaptyError) {
    // handle the error
  } catch (e) {
    // handle the error
  }
}

设置 appmetrica_profile_id


try {
    await Adapty().setIntegrationIdentifier(
        key: "appmetrica_profile_id", 
        value: "YOUR_APPMETRICA_PROFILE_ID",
    );
} on AdaptyError catch (adaptyError) {
    // handle the error
} catch (e) {
    // handle the error
}

设置 appmetrica_device_id

using AdaptySDK;
using Io.AppMetrica;

AppMetrica.RequestStartupParams(
    (result, errorReason) => {
        string deviceIdHash = result.DeviceIdHash;

        if (deviceIdHash != null) {
            Adapty.SetIntegrationIdentifier(
                "appmetrica_device_id",
                deviceIdHash,
                (error) => {
                    // handle the error
                });
          }
      },
      new List<string>() { StartupParamsKey.AppMetricaDeviceIDHash }
);

设置 appmetrica_profile_id

Adapty.SetIntegrationIdentifier(
  "appmetrica_profile_id",
  "YOUR_APPMETRICA_PROFILE_ID",
  (error) => {
    // handle the error
});

设置 appmetrica_device_id


// ...
const startupParamsCallback = async (
  params?: StartupParams,
  reason?: StartupParamsReason
) => {
  const deviceIdHash = params?.deviceIdHash
  if (deviceIdHash) {
    try {
      await adapty.setIntegrationIdentifier("appmetrica_device_id", deviceIdHash);
    } catch (error) {
      // handle `AdaptyError`
    }
  }
}

AppMetrica.requestStartupParams(startupParamsCallback, [DEVICE_ID_HASH_KEY])

设置 appmetrica_profile_id


try {
  await adapty.setIntegrationIdentifier("appmetrica_profile_id", 'YOUR_ADAPTY_CUSTOMER_USER_ID');
} catch (error) {
  // handle `AdaptyError`
}

AppMetrica 事件结构

Adapty 通过 POST 请求将事件发送到 AppMetrica，参数以查询参数的形式传递。对于每个 Adapty 事件，AppMetrica 最多会收到两个独立的请求：

用户画像事件（始终发送）：包含事件元数据
收入事件（可选）：如果在 Adapty 看板中启用了”Send revenue events”选项，则包含收入数据

用户画像事件请求

发送至：https://api.appmetrica.yandex.ru/logs/v1/import/events

带查询参数的示例 URL：

POST https://api.appmetrica.yandex.ru/logs/v1/import/events?post_api_key=your_key&application_id=your_app_id&event_name=subscription_renewed&event_timestamp=1709294400&event_json=%7B%22vendor_product_id%22%3A%22yearly.premium%22...%7D&os_name=ios&ios_ifa=00000000-0000-0000-0000-000000000000&ios_ifv=12345678-1234-1234-1234-123456789012&profile_id=user_12345&session_type=foreground

查询参数：

参数	类型	描述
`post_api_key`	String	您的 AppMetrica Post API Key。
`application_id`	String	您的 AppMetrica Application ID。
`event_name`	String	事件名称（从 Adapty 事件映射而来）。
`event_timestamp`	Long	事件的 UNIX 时间戳（单位：秒）。若早于最近 7 天则截断至 7 天前。
`event_json`	String	URL 编码的 JSON 字符串，包含所有可用的事件字段。仅包含非空字段。
`os_name`	String	”ios” 或 “android”。
`profile_id`	String	AppMetrica Profile ID（若已设置），否则为 Customer User ID（若可用）。
`appmetrica_device_id`	String	AppMetrica Device ID Hash。仅在 `profile_id` 不可用时发送。
`session_type`	String	始终为 “foreground”。
`ios_ifa`	String	仅限 iOS。广告主标识符（ID for Advertisers）。
`ios_ifv`	String	仅限 iOS。供应商标识符（ID for Vendors）。
`google_aid`	String	仅限 Android。Google 广告 ID。

收入事件请求（可选）

发送至：https://api.appmetrica.yandex.ru/logs/v1/import/revenue

仅当在 Adapty 看板集成设置中启用了”Send revenue events”选项时，才会发送此请求。

带查询参数的示例 URL：

POST https://api.appmetrica.yandex.ru/logs/v1/import/revenue?post_api_key=your_key&application_id=your_app_id&revenue_event_type=subscription_renewed&price=9.99&currency=USD&product_id=yearly.premium&quantity=1&transaction_id=GPA.3383...&payload=%7B%22vendor_product_id%22%3A%22yearly.premium%22...%7D&os_name=ios&ios_ifa=00000000-0000-0000-0000-000000000000&profile_id=user_12345&session_type=foreground

请求参数：

参数	类型	描述
`post_api_key`	String	您的 AppMetrica Post API Key。
`application_id`	String	您的 AppMetrica Application ID。
`revenue_event_type`	String	收入事件类型（例如 “subscription_renewed”、“refund”、“intro_started”）。请参阅 AppMetrica 事件映射。
`price`	Float	收入金额（基于您的收入计算设置）。
`currency`	String	货币代码（例如 “USD”）。
`product_id`	String	商店中的产品 ID。
`quantity`	Integer	固定为 1。
`transaction_id`	String	商店交易 ID。
`payload`	String	包含事件详情的 URL 编码 JSON 字符串。若超过 30KB，将按字段重要性顺序移除可选字段以自动裁剪，确保最关键的数据得以保留。
`os_name`	String	”ios” 或 “android”。
`profile_id`	String	AppMetrica Profile ID（若已设置），否则使用 Customer User ID（若可用）。
`appmetrica_device_id`	String	AppMetrica Device ID Hash。仅在 `profile_id` 不可用时发送。
`session_type`	String	固定为 “foreground”。
`ios_ifa`	String	仅限 iOS。广告主标识符（ID for Advertisers）。
`ios_ifv`	String	仅限 iOS。供应商标识符（ID for Vendors）。
`google_aid`	String	仅限 Android。Google 广告 ID。

故障排查

`access_level_updated` 在事件流中显示为失败

access_level_updated 是一个仅限 Webhook 的事件。Adapty 不会将其发送到此集成。但 Adapty 会为每个已启用的集成记录结果，不支持的事件将显示为失败。

AppMetrica

如何设置 AppMetrica 集成

看板配置

事件与标签

收入设置

SDK 配置

AppMetrica 事件结构

用户画像事件请求

收入事件请求（可选）

故障排查

access_level_updated 在事件流中显示为失败

`access_level_updated` 在事件流中显示为失败