---
metadata:
  - name: generator
    content: Diplodoc Platform v5.63.4
alternate:
  - https://appmetrica.yandex.com/docs/en/sdk/flutter/analytics/flutter-operations.md
  - https://appmetrica.yandex.com/docs/ru/sdk/flutter/analytics/flutter-operations.md
  - https://appmetrica.yandex.com/docs/zh/sdk/flutter/analytics/flutter-operations.md
  - href: https://appmetrica.yandex.com/docs/zh/sdk/flutter/analytics/flutter-operations.md
    type: text/markdown
    title: Markdown version
  - href: https://appmetrica.yandex.com/docs/zh/llms.txt?revision=r21698989
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://appmetrica.yandex.com/docs/zh/llms.txt?revision=r21698989

# 使用示例

## 使用扩展配置初始化库 {#initialize}

要用扩展的启动配置初始化库，请传递一个`AppMetricaConfig`实例，设置相应的参数，然后通过`AppMetrica.activate(AppMetricaConfig config)`方法激活库。 使用扩展配置，您可以启用或禁用日志记录、设置会话超时、传递跟踪预安装应用的参数等。

扩展配置设置在库初始化时立即生效。

```java translate=no
AppMetrica.activate(
      AppMetricaConfig(API_KEY, logs: true
          // ...
          ));
```

## 向额外的API密钥发送统计数据 {#reporter-different-apikey}

将数据发送到额外的 API 密钥可以让您为这些 API 密钥收集自己的统计数据。 你可以用这来控制其他用户对信息的访问权限。 例如，为了给分析师提供统计数据的访问权限，可以为额外的 API 密钥复制发送营销数据。 这样他们只会有访问所需信息的权限。

要将数据发送到额外的 API 密钥，必须使用报告器。 就像主 API 密钥一样，你可以为报告员设置扩展的启动配置，发送事件、个人资料信息和应用内购买的数据。 报告器可以在不初始化AppMetrica SDK的情况下工作。

### 步骤 1. (可选) 使用扩展配置初始化报告器 {#reporter-different-apikey-initialize}

要用扩展配置初始化报告器，请创建 `AppMetricaReporterConfig` 类的实例，并指定必要的配置。 然后，使用 `AppMetrica.activateReporter(AppMetricaReporterConfig reporterConfig)` 方法激活报告器。 此配置用于具有指定 API 密钥的报告员。 您可以为每个附加的 API 密钥设置自己的配置。

{% note alert %}

在第一次调用报告器之前，应先初始化具有扩展配置的报告器。 否则，报告器将在没有配置的情况下初始化。

{% endnote %}

```dart translate=no
// Creating extended configuration of the reporter.
// To create it, pass a ANOTHER_API_KEY that is different from the app's API_KEY.
AppMetricaReporterConfig reporterConfig = AppMetricaReporterConfig("ANOTHER_API_KEY",
    // Setting up the configuration. For example, to enable logging.
    logs: true);
// Initializing a reporter.
AppMetrica.activateReporter(reporterConfig);
```

### 步骤 2. 配置使用报告器发送数据 {#reporter-different-apikey-send}

要使用报告器发送数据，首先通过调用 `AppMetricaReporter` 抽象类的 `AppMetrica.getReporter(String apiKey)` 方法获取实现该类的对象。 然后，使用接口方法发送报告。 如果报告器没有用扩展配置进行初始化，调用此方法将为指定的API密钥初始化报告器。

事件发送示例：

```dart translate=no
AppMetrica.getReporter("ANOTHER_API_KEY").reportEvent("Updates installed");
```

为了正确追踪，请手动配置报告器，为每个报告器发送会话开始和暂停的事件。 对于此目的，请使用 `resumeSession()` 和 `pauseSession()` 方法：

```dart translate=no
AppMetricaReporter reporter = AppMetrica.getReporter("ANOTHER_API_KEY");
reporter.resumeSession();
reporter.reportEvent("Updates installed");
reporter.pauseSession();
```

## 使用库发送设备位置 {#track-location}

默认情况下，Android 设备位置发送已禁用。 要启用发送功能，请用配置初始化库，其中已启用发送设备位置数据。 要做到这一点，在创建扩展库配置时，将`locationTracking`属性设置为`true`：

```java translate=no
AppMetrica.activate(AppMetricaConfig(API_KEY,
	locationTracking: true));
```

要在应用运行时启用发送，请使用`AppMetrica.setLocationTracking(bool enabled)` 方法：

```java translate=no
AppMetrica.setLocationTracking(true);
```

为了更精确的定位，请在 AndroidManifest.xml 文件中添加以下权限之一：

- `android.permission.ACCESS_COARSE_LOCATION` — 用于粗略定位。
- `android.permission.ACCESS_FINE_LOCATION` — 用于精确定位。

## 手动设置位置 {#location-manual}

在发送设备位置的自定义信息之前，请确保已启用报告发送功能。

库会自行确定设备位置。 要发送自定义的设备位置数据，请将 `AppMetricaLocation` 传递给 `AppMetrica.setLocation(AppMetricaLocation? location)` 方法：

```java translate=no
// Determining the location.
AppMetricaLocation location = AppMetricaLocation(latitude, longitude);
//  Setting up custom device location data.
AppMetrica.setLocation(location);
```

要使用扩展配置发送自定义设备位置，在创建扩展库配置时，将`AppMetricaLocation`实例传递给`location`属性：

```java translate=no
AppMetricaLocation location = AppMetricaLocation(latitude, longitude);
AppMetrica.activate(AppMetricaConfig(API_KEY,
	location: location));
```

## 发送自定义事件 {#report-event}

要发送自定义事件（不包含嵌套参数），请将事件的短名称或描述传递给 `AppMetrica.reportEvent(String eventName)` 方法：

```dart translate=no
AppMetrica.reportEvent("eventName");
```

## 发送自定义事件（包含嵌套参数） {#report-event-params}

要发送 JSON 格式的参数：

```dart translate=no
String jsonAttributes = '{"item":"book","price":9.99}';

AppMetrica.reportEventWithJson("Purchase", jsonAttributes);
```

要将参数作为 Map 对象发送：

```dart translate=no
Map<String, dynamic> attributesMap = {"item": "book", "price": 9.99};
AppMetrica.reportEventWithMap("Purchase", attributesMap);
```

## 发送自定义错误消息 {#send-report-error}

要发送自定义错误消息，请使用以下方法：

```dart translate=no
AppMetrica.reportError(
  message: "Error occurred",
  errorDescription: AppMetricaErrorDescription(StackTrace.current),
);
```

要发送包含组 ID 的错误消息：

```dart translate=no
AppMetrica.reportErrorWithGroup(
  "IDENTIFIER",
  message: "MESSAGE",
  errorDescription: AppMetricaErrorDescription(StackTrace.current),
);
```

## 从缓冲区发送事件 {#send-events-buffer}

AppMetrica SDK 不会在事件发生后立即发送事件。 库存将事件数据保存在缓冲区中。 The `sendEventsBuffer` 方法从缓冲区发送数据并清空缓冲区。 使用该方法在用户场景的重要检查点之后强制发送已存储的事件。

```dart translate=no
AppMetrica.sendEventsBuffer();
```

{% note alert "" %}

如果您经常使用此方法，可能会导致互联网流量和电力消耗增加。

{% endnote %}

## 手动监控应用生命周期 {#listen}

AppMetrica 自动跟踪会话边界。 如果需要，您可以通过在扩展库配置中将 `false` 传递给 `SessionsAutoTrackingEnabled` 属性来禁用自动会话跟踪。

```dart translate=no
AppMetrica.activate(
    AppMetricaConfig(API_KEY, sessionsAutoTrackingEnabled: false));
```

要手动监控应用生命周期，请使用以下方法：

- 暂停会话：

   ```dart translate=no
   AppMetrica.pauseSession();
   ```

- 恢复会话或开始新会话：

   ```dart translate=no
   AppMetrica.resumeSession();
   ```

## 跟踪应用崩溃 {#set-report-crash}

默认会发送应用崩溃的报告。

要禁用自动监控，请用禁止发送崩溃报告的配置初始化库。 要做到这一点，在创建扩展库配置时，将 `false` 值传递给 `crashReporting` 和 `flutterCrashReporting` 属性。

```dart translate=no
AppMetrica.activate(AppMetricaConfig("daa46e63-d4a6-46d1-bbf9-0dcf4b482b83",
    // Disabling the data sending about the native android/ios crashes.
    crashReporting: false,
    // Disabling the data sending about the Flutter crashes.
    flutterCrashReporting: false));
```

## 手动监控应用崩溃 {#report-unhandled}

应用程序崩溃的报告默认会被发送。 为了防止手动发送崩溃时事件重复，请禁用应用崩溃的自动监控。

要手动发送崩溃数据，请使用`AppMetrica.reportUnhandledException(AppMetricaErrorDescription errorDescription)` 方法。

```dart translate=no
AppMetrica.reportUnhandledException(
  AppMetricaErrorDescription.fromCurrentStackTrace(
      message: 'Error message', type: 'Error type'),
);
```

## 发送 ProfileId {#send-profile-id}

如果在初始化 AppMetrica SDK 之前已知用户资料 ID，请在初始化前传入 (`setUserProfileID`) 或在使用扩展配置进行初始化时传入 (`withUserProfileID`)。

否则，将使用 ID `appmetrica_device_id` 创建技术配置文件。

您可以在任何时间通过调用 `ProfileId` 来更新 `setUserProfileID`：

```dart translate=no
AppMetrica.setUserProfileID("id");
```

## 发送个人属性 {#send-attribute-profile}

要发送用户属性，请将 `UserProfile` 类的实例传递给 `AppMetrica.reportUserProfile(UserProfile)` 方法。

```dart translate=no
AppMetricaUserProfile userProfile = AppMetricaUserProfile([
  // Updating predefined attributes.
  AppMetricaNameAttribute.withValue("John"),
  AppMetricaGenderAttribute.withValue(AppMetricaGender.male),
  AppMetricaBirthDateAttribute.withAge(24),
  AppMetricaNotificationEnabledAttribute.withValue(false),

  // Updating custom attributes.
  AppMetricaStringAttribute.withValue("string_attribute", "string"),
  AppMetricaNumberAttribute.withValue("number_attribute", 55),
  AppMetricaCounterAttribute.withDelta("counter_attribute", 1)
]);

// Setting the ProfileID using the method of the YandexMetrica class.
AppMetrica.setUserProfileID("id");

// Sending the UserProfile instance.
AppMetrica.reportUserProfile(userProfile);
```

## 发送电子商务事件 {#send-ecommerce}

AppMetrica 不允许将电商事件分为测试事件和非测试事件。 如果你使用主 API 密钥调试购买，测试事件会被包含在总体统计中。 因此，要调试电商事件发送，请使用报告器将统计数据发送到额外的API密钥。

### 步骤 1. 在 AppMetrica 中创建测试应用 {#send-ecom-test}

请指定应用参数：应用商店中的链接（如果应用尚未发布，请留空）、名称、类别以及生成报告的时区。

要添加另一个应用，请点击[添加应用](https://appmetrica.yandex.com/application/new)，在AppMetrica的下拉列表中。

### 步骤 2. 配置将电子商务事件发送到测试 API 密钥 {#send-ecom-test-key}

对于不同的用户操作，存在相应的电商事件类型。 要创建特定事件类型，请使用适当的`AppMetricaECommerce`类方法。

下面的示例展示了如何发送特定类型的事件。

{% cut "打开页面" %}

```dart translate=no
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true",
};
// Creating a screen object.
AppMetricaECommerceScreen screen = AppMetricaECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "danissimo maple syrup", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Promos", "Hot deal"] // Optional.
    );
AppMetricaECommerceEvent showScreenEvent = AppMetricaECommerce.showScreenEvent(screen);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key").reportECommerce(showScreenEvent);
```

{% endcut %}

{% cut "查看产品卡片" %}

```dart translate=no
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true"
};
// Creating a screen object.
AppMetricaECommerceScreen screen = AppMetricaECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "danissimo maple syrup", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Promos", "Hot deal"] // Optional.
    );
AppMetricaECommerceAmount amount =
    AppMetricaECommerceAmount(amount: Decimal.parse('4.53'), currency: "USD");
// Creating an actualPrice object.
AppMetricaECommercePrice actualPrice =
    AppMetricaECommercePrice(fiat: amount, internalComponents: [
  // Optional.
  AppMetricaECommerceAmount(amount: Decimal.parse('30_570_000'), currency: "wood"),
  AppMetricaECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
  AppMetricaECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
]);
// Creating an originalPrice object.
AppMetricaECommercePrice originalPrice = AppMetricaECommercePrice(
    fiat: AppMetricaECommerceAmount(amount: Decimal.parse('5.78'), currency: "USD"),
    internalComponents: [
      // Optional.
      AppMetricaECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
      AppMetricaECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
      AppMetricaECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
    ]);
// Creating a product object.
AppMetricaECommerceProduct product = AppMetricaECommerceProduct(
    sku: "779213",
    name: "Danissimo curd product 5.9%, 130 g", // Optional.
    actualPrice: actualPrice, // Optional.
    originalPrice: originalPrice, // Optional.
    promocodes: ["BT79IYX", "UT5412EP"], // Optional.
    payload: payload, // Optional.
    categoriesPath: [
      "Groceries",
      "Dairy",
      "Yogurts"
    ] // Optional.
    );
AppMetricaECommerceEvent showProductCardEvent =
    AppMetricaECommerce.showProductCardEvent(product, screen);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key")
    .reportECommerce(showProductCardEvent);
```

{% endcut %}

{% cut "查看产品页面" %}

```dart translate=no
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true"
};
// Creating a screen object.
AppMetricaECommerceScreen screen = AppMetricaECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "danissimo maple syrup", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Promos", "Hot deal"] // Optional.
    );
AppMetricaECommerceAmount amount =
    AppMetricaECommerceAmount(amount: Decimal.parse('4.53'), currency: "USD");
// Creating an actualPrice object.
AppMetricaECommercePrice actualPrice =
    AppMetricaECommercePrice(fiat: amount, internalComponents: [
  // Optional.
  AppMetricaECommerceAmount(amount: Decimal.parse('30_570_000'), currency: "wood"),
  AppMetricaECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
  AppMetricaECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
]);
// Creating an originalPrice object.
AppMetricaECommercePrice originalPrice = AppMetricaECommercePrice(
    fiat: AppMetricaECommerceAmount(amount: Decimal.parse('5.78'), currency: "USD"),
    internalComponents: [
      // Optional.
      AppMetricaECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
      AppMetricaECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
      AppMetricaECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
    ]);
// Creating a product object.
AppMetricaECommerceProduct product = AppMetricaECommerceProduct(
    sku: "779213",
    name: "Danissimo curd product 5.9%, 130 g", // Optional.
    actualPrice: actualPrice, // Optional.
    originalPrice: originalPrice, // Optional.
    promocodes: ["BT79IYX", "UT5412EP"], // Optional.
    payload: payload, // Optional.
    categoriesPath: [
      "Groceries",
      "Dairy",
      "Yogurts"
    ] // Optional.
    );
AppMetricaECommerceEvent showProductDetailsEvent =
    AppMetricaECommerce.showProductDetailsEvent(product, screen);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key")
    .reportECommerce(showProductDetailsEvent);
```

{% endcut %}

{% cut "将物品添加到购物车/从购物车中移除" %}

```dart translate=no
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true"
};
// Creating a screen object.
AppMetricaECommerceScreen screen = AppMetricaECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "danissimo maple syrup", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Promos", "Hot deal"] // Optional.
    );
AppMetricaECommerceAmount amount =
    AppMetricaECommerceAmount(amount: Decimal.parse('4.53'), currency: "USD");
// Creating an actualPrice object.
AppMetricaECommercePrice actualPrice =
    AppMetricaECommercePrice(fiat: amount, internalComponents: [
  // Optional.
  AppMetricaECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
  AppMetricaECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
  AppMetricaECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
]);
// Creating an originalPrice object.
AppMetricaECommercePrice originalPrice = AppMetricaECommercePrice(
    fiat: AppMetricaECommerceAmount(amount: Decimal.parse('5.78'), currency: "USD"),
    internalComponents: [
      // Optional.
      AppMetricaECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
      AppMetricaECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
      AppMetricaECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
    ]);
// Creating a product object.
AppMetricaECommerceProduct product = AppMetricaECommerceProduct(
    sku: "779213",
    name: "Danissimo curd product 5.9%, 130 g", // Optional.
    actualPrice: actualPrice, // Optional.
    originalPrice: originalPrice, // Optional.
    promocodes: ["BT79IYX", "UT5412EP"], // Optional.
    payload: payload, // Optional.
    categoriesPath: [
      "Groceries",
      "Dairy",
      "Yogurts"
    ] // Optional.
    );
AppMetricaECommerceReferrer referrer = AppMetricaECommerceReferrer(
    type: "button", // Optional.
    identifier: "76890", // Optional.
    screen: screen // Optional.
    );
// Creating a cartItem object.
AppMetricaECommerceCartItem addedItems1 = AppMetricaECommerceCartItem(
    product: product,
    revenue: actualPrice,
    quantity: Decimal.parse("1.0"),
    referrer: referrer // Optional.
    );
AppMetricaECommerceEvent addCartItemEvent = AppMetricaECommerce.addCartItemEvent(addedItems1);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key").reportECommerce(addCartItemEvent);
AppMetricaECommerceEvent removeCartItemEvent =
    AppMetricaECommerce.removeCartItemEvent(addedItems1);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key")
    .reportECommerce(removeCartItemEvent);
```

{% endcut %}

{% cut "开始并完成购买" %}

```dart translate=no
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true"
};
// Creating a screen object.
AppMetricaECommerceScreen screen = AppMetricaECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "danissimo maple syrup", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Promos", "Hot deal"] // Optional.
    );
AppMetricaECommerceAmount amount =
    AppMetricaECommerceAmount(amount: Decimal.parse('4.53'), currency: "USD");
// Creating an actualPrice object.
AppMetricaECommercePrice actualPrice =
    AppMetricaECommercePrice(fiat: amount, internalComponents: [
  // Optional.
  AppMetricaECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
  AppMetricaECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
  AppMetricaECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
]);
// Creating an originalPrice object.
AppMetricaECommercePrice originalPrice = AppMetricaECommercePrice(
    fiat: AppMetricaECommerceAmount(amount: Decimal.parse('5.78'), currency: "USD"),
    internalComponents: [
      // Optional.
      AppMetricaECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
      AppMetricaECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
      AppMetricaECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
    ]);
// Creating a product object.
AppMetricaECommerceProduct product = AppMetricaECommerceProduct(
    sku: "779213",
    name: "Danissimo curd product 5.9%, 130 g", // Optional.
    actualPrice: actualPrice, // Optional.
    originalPrice: originalPrice, // Optional.
    promocodes: ["BT79IYX", "UT5412EP"], // Optional.
    payload: payload, // Optional.
    categoriesPath: [
      "Groceries",
      "Dairy",
      "Yogurts"
    ] // Optional.
    );
AppMetricaECommerceReferrer referrer = AppMetricaECommerceReferrer(
    type: "button", // Optional.
    identifier: "76890", // Optional.
    screen: screen // Optional.
    );
// Creating a cartItem object.
AppMetricaECommerceCartItem addedItems1 = AppMetricaECommerceCartItem(
    product: product,
    revenue: actualPrice,
    quantity: Decimal.parse("1.0"),
    referrer: referrer // Optional.
    );
// Creating an order object.
AppMetricaECommerceOrder order = AppMetricaECommerceOrder(
    identifier: "88528768",
    items: [addedItems1],
    payload: payload // Optional.
    );
AppMetricaECommerceEvent beginCheckoutEvent = AppMetricaECommerce.beginCheckoutEvent(order);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key")
    .reportECommerce(beginCheckoutEvent);
AppMetricaECommerceEvent purchaseEvent = AppMetricaECommerce.purchaseEvent(order);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key").reportECommerce(purchaseEvent);
```

{% endcut %}

### 步骤 3. 查看测试应用的报告 {#send-ecom-check-reports}

在应用中进行测试购买。 过一会儿，在 AppMetrica 界面中检查电商报告。 确保报告显示电子商务事件。 要了解报告的更多信息，请查看[电子商务](https://appmetrica.yandex.com/docs/zh/mobile-reports/ecommerce-report.md)。

### 第4步。 配置将电子商务数据发送到主 API Key {#send-ecom-key}

测试成功后，配置将电子商务事件发送到主 API 密钥。

要将`AppMetricaECommerceEvent`对象发送到主API密钥，请使用`AppMetrica.reportECommerce(AppMetricaECommerceEvent event)`方法：

```dart translate=no
...
// Sending an E-commerce event.
AppMetrica.reportECommerce(ecommerceEvent);
```

## 发送应用内购买 {#send-revenue}

{% cut "带验证" %}

要验证 Android 上的购买，请配置发送 `Revenue.Receipt` 实例以及 Revenue。 对于 iOS，配置发送 `transactionID` 字段。

1. 创建一个`AppMetricaReceipt`实例，包含购买信息和签名。
2. 创建一个`AppMetricaRevenue`实例，并将`AppMetricaReceipt`和`transactionID`传递给它。
3. 发送 `AppMetricaRevenue` 实例，使用 `AppMetrica.reportRevenue(AppMetricaRevenue revenue)` 方法。

```java translate=no
AppMetricaReceipt receipt = AppMetricaReceipt(
	data: billingClientPurchase.originalJson,
	signature: billingClientPurchase.signature);
AppMetricaRevenue revenue = AppMetricaRevenue(
	Decimal.parse("100.100"),
	"USD",
	quantity: 2,
	productId: "com.yandex.service.299",
	payload: "{\"source\":\"Google Play\"}",
	receipt: receipt,
	transactionId: transactionIdentifier);
AppMetrica.reportRevenue(revenue);
```

{% endcut %}

{% cut "不带验证" %}

1. 创建一个`AppMetricaRevenue`实例。

2. (可选) 要按 `OrderID` 分组购买，请将其传递到 `payload` 属性。

{% note info "注意" %}

如果没有指定`OrderID`，AppMetrica会自动生成ID。

{% endnote %}

3. 发送 `AppMetricaRevenue` 实例，使用 `AppMetrica.reportRevenue(AppMetricaRevenue revenue)` 方法。

```java translate=no
AppMetricaRevenue revenue = AppMetricaRevenue(Decimal.parse("100.100"), "USD",
	quantity: 2,
	productId: "com.yandex.service.299",
	payload: """{"OrderID":"Identifier", "source":"Google Play"}""");
AppMetrica.reportRevenue(revenue);
```

{% endcut %}

## 发送广告收入 {#send-adrevenue}

您可以传输广告收入信息到 AppMetrica。

### 步骤 1. 确保 SDK 已激活 {#send-adrevenue-active}

激活示例：

```dart translate=no
AppMetricaConfig config = AppMetricaConfig("API_KEY");
AppMetrica.activate(config);
```

### 步骤 2. 设置广告收入数据发送 {#send-adrevenue-send}

1. 创建一个`AppMetricaAdRevenue`类对象。

   ```dart translate=no
    Map<String, String> adRevenuePayload = {
      "payload_key_1": "payload_value_1",
      "payload_key_2": "payload_value_2"
    };

    AppMetricaAdRevenue adRevenue = AppMetricaAdRevenue(
        adRevenue: Decimal.parse("100.100"),
        currency: "USD",
        adNetwork: "ad_network", // Optional
        adPlacementId: "ad_placement_id", // Optional
        adPlacementName: "ad_placement_name", // Optional
        adType: AdType.NATIVE, // Optional
        adUnitId: "ad_unit_id", // Optional
        adUnitName: "ad_unit_name", // Optional
        precision: "some precision", // Optional
        payload: adRevenuePayload // Optional
        );
   ```

2. 发送 `AppMetricaAdRevenue` 实例，使用 `reportAdRevenue(AppMetricaAdRevenue adRevenue)` 方法。

   ```dart translate=no
   AppMetrica.reportAdRevenue(adRevenue);
   ```

### 步骤 3. 确保广告收入数据被包含在报告中 {#send-adrevenue-check-reports}

1. 在应用中查看广告。

2. 确保[应用内和广告收入](https://appmetrica.yandex.com/docs/zh/mobile-reports/revenue-report.md)报告中广告收入事件的数量与广告浏览数量一致。

## 通过深链路跟踪应用打开 {#deeplink}

使用 `reportAppOpen(String deeplink)` 方法来跟踪应用启动：

```dart translate=no
AppMetrica.reportAppOpen(deeplink);
```

## 设置会话超时时长 {#session-timeout}

默认情况下，会话超时时间为10秒。 参数 `sessionTimeout` 的最小可接受值为 10 秒。

要更改超时时长，在创建扩展库配置时，将秒数传递给 `sessionTimeout` 属性。

```dart translate=no
AppMetrica.activate(
    AppMetricaConfig(API_KEY, sessionTimeout: 15));
```

## 设置应用版本 {#version-app}

要在代码中手动指定应用版本，请在创建扩展库配置时将其传递给 `appVersion` 属性。

```dart translate=no
AppMetrica.activate(
    AppMetricaConfig(API_KEY, appVersion: "1.13.2"));
```

where `1.13.2` 是应用版本。


## 确定库的API级别（Android） {#level-api-android}

要从应用代码确定库的 API 级别，请使用 `libraryApiLevel` 属性。

```dart translate=no
int apiLevel;
AppMetrica.libraryApiLevel.then((value) => {apiLevel = value});
```

## 确定库的版本 {#version-sdk}

要从应用程序代码中确定库版本，请使用`AppMetrica.GetLibraryVersion()` 方法。

```dart translate=no
String version;
AppMetrica.libraryVersion.then((value) => {version = value});
```

## 请求延迟深链 {#deferreddeeplink-request}

要请求延迟深链，请调用`AppMetrica.requestDeferredDeeplink()` 方法。 你只能在获取 Google Play Install Referrer 后的第一次应用启动时请求延迟深链。

```dart translate=no
AppMetrica.requestDeferredDeeplink()
    .then((value) => {
          // Processing deferred deeplink.
        })
    .onError((error, stackTrace) => {
          // Handling the error.
        });
```

关于延迟深链的更多信息，请参见[延迟深链支持](https://appmetrica.yandex.com/docs/zh/sdk/android/analytics/android-deferred-deeplinks.md)。

## 请求延迟深度链接参数 {#deferreddeeplink-parameters-request}

要请求延迟深链的参数，请调用 `AppMetrica.requestDeferredDeeplinkParameters()` 方法。 你只能在获取 Google Play Install Referrer 后的第一次应用启动时请求延迟深链参数。

```dart translate=no
AppMetrica.requestDeferredDeeplinkParameters()
    .then((value) => {
          // Processing deeplink parameters.
        })
    .onError((error, stackTrace) => {
          // Handling the error.
        });
```

关于延迟深链的更多信息，请参见[延迟深链支持](https://appmetrica.yandex.com/docs/zh/sdk/android/analytics/android-deferred-deeplinks.md)。

## 跟踪新用户 {#new-user}

默认情况下，当应用程序第一次打开时，用户会被视为新用户。 如果你将 AppMetrica SDK 连接到已有活跃用户的应用，可以设置跟踪新旧用户，以获取准确的统计数据。 通过初始化 AppMetrica SDK，使用扩展的 `AppMetricaConfig` 配置来进行设置：

```dart translate=no
bool isFirstLaunch = false;
// Implement logic to detect whether the app is opening for the first time.
// For example, you can check for files (settings, databases, and so on),
// which the app creates on its first launch.
if (conditions) {
  isFirstLaunch = true;
}
// Activating SDK with extended library configuration.
AppMetrica.activate(
    AppMetricaConfig(API_KEY, firstActivationAsUpdate: !isFirstLaunch));
```

## 禁用和启用发送统计数据 {#stat}

如果需要在发送统计数据前获得用户确认，请将库初始化为禁用发送选项。 要做到这一点，在创建扩展库配置时，将 `false` 值传递给 `dataSendingEnabled` 属性。

```dart translate=no
AppMetrica.activate(
    AppMetricaConfig(API_KEY, dataSendingEnabled: false));
```

在用户同意发送统计数据后（例如在应用设置中或第一次启动应用时接受协议），使用 `AppMetrica.setDataSendingEnabled(bool enabled)` 方法启用统计数据发送：

```dart translate=no
// Checking the status of the boolean variable. It shows the user confirmation.
if (flag) {
  // Enabling sending data.
  AppMetrica.setDataSendingEnabled(true);
}
```

### 警告示例 {#stat-example}

您可以使用任何文本来告知用户统计数据的收集。 例如：

此应用使用由 YANDEX LLC 提供的AppMetrica分析服务，地址为俄罗斯莫斯科列夫·托尔斯泰街16号，邮编119021（以下简称 Yandex），基于[使用条款](https://yandex.ru/legal/metrica_termsofuse/?lang=zh)。

AppMetrica 分析应用使用数据，包括运行设备、安装来源，计算转化率，收集您的活动统计，用于产品分析、广告活动分析与优化，以及故障排查。 通过这种方式收集的信息无法识别您的身份。

由 AppMetrica 工具收集的关于您使用此应用的去标识化信息将被传输至 Yandex，并存储在位于欧盟和俄罗斯联邦的 Yandex 服务器上. Yandex 将处理这些信息，以提供应用使用统计数据、生成应用性能报告并提供其他服务。


## 获取 AppMetrica SDK ID {#get-ids}

要获取 AppMetrica SDK ID（`DeviceId`、`DeviceIdHash`、`UUID`），请使用 `requestStartupParams()` 方法。 要获取`appmetrica_device_id`，请确保请求`DeviceIdHash`.

```dart translate=no
Future<AppMetricaStartupParams> params = AppMetrica.requestStartupParams([
  AppMetricaStartupParams.deviceIdHashKey,
  AppMetricaStartupParams.deviceIdKey,
  AppMetricaStartupParams.uuidKey
]);
params.then((value) => {
      print(value.result?.deviceIdHash),
      print(value.result?.deviceId),
      print(value.result?.uuid)
    });
```

<!-- source: zh/_includes/feedback-button-3.md -->
如果您没有找到所需答案，可以通过反馈表单提交您的问题。 请尽可能详细地描述问题。 如果可能，请附上截图。

<a href="../troubleshooting/feedback-new">
  <span class="button">联系支持</span>
</a>

<a href="../troubleshooting/feedback-docs">
  <span class="button">为文档提出改进建议</span>
</a>
<!-- endsource: zh/_includes/feedback-button-3.md -->