Примеры использования методов

Отправка статистики на дополнительный API key

Отправка данных на дополнительный API key позволяет собирать для каждого API key свою статистику. Это можно использовать для управления доступом к информации. Например, чтобы предоставить доступ к статистике для аналитиков, можно продублировать отправку маркетинговых данных на дополнительный API key и предоставить им доступ к этой статистике. Так у них будет доступ только к той информации, которая им необходима.

Для отправки данных на дополнительный API key необходимо использовать репортеры. С помощью них можно отправлять события, сообщения об ошибках, профили и информацию о покупках в приложении. Репортеры могут работать без инициализации AppMetrica SDK.

Шаг 1. (Опционально) Инициализируйте репортер с расширенной конфигурацией

Чтобы инициализировать репортер с расширенной конфигурацией, создайте объект класса AppMetricaReporterConfig с необходимыми настройками и активируйте репортер с помощью метода AppMetrica.activateReporter(AppMetricaReporterConfig reporterConfig). Конфигурация применяется для репортера с указанным API key. Для каждого дополнительного API key можно настроить свою конфигурацию.

Внимание

Инициализацию репортера с расширенной конфигурацией необходимо проводить до первого обращения к репортеру. Иначе репортер будет инициализирован без конфигурации.

// 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. Настройте отправку данных с помощью репортера

Для отправки данных с помощью репортера, необходимо получить объект, который реализует абстрактный класс AppMetricaReporter с помощью метода AppMetrica.getReporter(String apiKey), и использовать методы интерфейса для отправки отчетов. Если репортер не был инициализирован с расширенной конфигурацией, то вызов данного метода произведет инициализацию репортера для указанного API key.

Пример отправки события:

AppMetrica.getReporter("ANOTHER_API_KEY").reportEvent("Updates installed");

Для корректного отслеживания сессий взаимодействия пользователя с приложением настройте отправку событий о начале и приостановке сессии для каждого репортера. Для этого используйте методы resumeSession() и pauseSession():

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

Отправка собственного события

Чтобы отправить собственное событие без вложенных параметров, передайте короткое название или описание события в метод AppMetrica.reportEvent(String eventName):

AppMetrica.reportEvent("eventName");

Отправка собственного события с вложенными параметрами

Чтобы передать параметры в формате JSON:

String jsonAttributes = '{"item":"book","price":9.99}';

AppMetrica.reportEventWithJson("Purchase", jsonAttributes);

Чтобы передать параметры в формате Map:

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

Отправка собственного сообщения об ошибке

Чтобы отправить собственное сообщение об ошибке, используйте метод:

AppMetrica.reportError(
  message: "Error occurred",
  errorDescription: AppMetricaErrorDescription(StackTrace.current),
);

Для отправки сообщения об ошибке с идентификатором группы:

AppMetrica.reportErrorWithGroup(
  "IDENTIFIER",
  message: "MESSAGE",
  errorDescription: AppMetricaErrorDescription(StackTrace.current),
);

Отправка событий из буфера

AppMetrica SDK не отправляет событие сразу после того, как оно произошло. Библиотека хранит данные о событиях в буфере. Метод sendEventsBuffer отправляет данные из буфера и очищает его. Используйте этот метод для принудительной отправки сохраненных событий после прохождения важных сценариев пользователя.

AppMetrica.sendEventsBuffer();

Отслеживание жизненного цикла приложения вручную

Для отслеживания жизненного цикла используйте методы:

  • Приостановка сессии:

    AppMetrica.pauseSession();
    
  • Возобновление или начало новой сессии:

    AppMetrica.resumeSession();
    

Отслеживание аварийных остановок приложения вручную

Отчеты об аварийных остановках приложения отправляются по умолчанию. Чтобы избежать дублирования событий при ручной отправке, необходимо отключить автоматическое отслеживание аварийных остановок.

Чтобы отправлять информацию об аварийных остановках приложения вручную, используйте метод AppMetrica.reportUnhandledException(AppMetricaErrorDescription errorDescription):

Отправка ProfileId

Если идентификатор пользовательского профиля известен до инициализации AppMetrica SDK, передавайте его до инициализации (setUserProfileID) или во время инициализации с расширенной конфигурацией (withUserProfileID).

В противном случае будет создан технический профиль с идентификатором appmetrica_device_id.

В любой момент можно обновить ProfileId с помощью вызова setUserProfileID:

AppMetrica.setUserProfileID("id");

Отправка атрибутов профиля

Чтобы отправить атрибуты профиля, передайте в метод AppMetrica.reportUserProfile(UserProfile) объект класса UserProfile.

UserProfile userProfile = UserProfile([
  // Updating predefined attributes.
  NameAttribute.withValue("John"),
  GenderAttribute.withValue(Gender.MALE),
  BirthDateAttribute.withAge(24),
  NotificationEnabledAttribute.withValue(false),

  // Updating custom attributes.
  StringAttribute.withValue("string_attribute", "string"),
  NumberAttribute.withValue("number_attribute", 55),
  CounterAttribute.withDelta("counter_attribute", 1)
]);

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

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

Отправка ECommerce-событий на Flutter

В AppMetrica нет возможности сегментировать ECommerce-события на «тестовые» и «не тестовые». Если для отладки покупок вы используете основной API key, то тестовые события будут попадать в общую статистику. Поэтому чтобы отладить отправку ECommerce-событий, используйте отправку статистики на дополнительный API key с помощью репортера.

Шаг 1. Создайте тестовое приложение в AppMetrica

Заполните параметры приложения: ссылка в магазине приложений (если приложение еще не опубликовано — оставьте поле пустым), название, категория, часовой пояс для построения отчетов.

Чтобы добавить еще одно приложение, нажмите кнопку Добавить приложение в выпадающем списке в интерфейсе AppMetrica.

Шаг 2. Настройте отправку ECommerce-событий на тестовый API key

Для различных действий пользователя есть соответствующие типы ECommerce-событий. Чтобы создать конкретный тип события, используйте нужный метод класса ECommerce.

Ниже приведены примеры отправки конкретных типов событий.

Открытие страницы
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true",
};
// Creating a screen object.
ECommerceScreen screen = ECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "даниссимо кленовый сироп", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Акции", "Красная цена"] // Optional.
    );
ECommerceEvent showScreenEvent = ECommerce.showScreenEvent(screen);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key").reportECommerce(showScreenEvent);
Просмотр карточки товара
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true"
};
// Creating a screen object.
ECommerceScreen screen = ECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "даниссимо кленовый сироп", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Акции", "Красная цена"] // Optional.
    );
ECommerceAmount amount =
    ECommerceAmount(amount: Decimal.parse('4.53'), currency: "USD");
// Creating an actualPrice object.
ECommercePrice actualPrice =
    ECommercePrice(fiat: amount, internalComponents: [
  // Optional.
  ECommerceAmount(amount: Decimal.parse('30_570_000'), currency: "wood"),
  ECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
  ECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
]);
// Creating an originalPrice object.
ECommercePrice originalPrice = ECommercePrice(
    fiat: ECommerceAmount(amount: Decimal.parse('5.78'), currency: "USD"),
    internalComponents: [
      // Optional.
      ECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
      ECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
      ECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
    ]);
// Creating a product object.
ECommerceProduct product = ECommerceProduct(
    sku: "779213",
    name: "Продукт творожный «Даниссимо» 5.9%, 130 г.", // Optional.
    actualPrice: actualPrice, // Optional.
    originalPrice: originalPrice, // Optional.
    promocodes: ["BT79IYX", "UT5412EP"], // Optional.
    payload: payload, // Optional.
    categoriesPath: [
      "Продукты",
      "Молочные продукты",
      "Йогурты"
    ] // Optional.
    );
ECommerceEvent showProductCardEvent =
    ECommerce.showProductCardEvent(product, screen);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key")
    .reportECommerce(showProductCardEvent);
Просмотр страницы товара
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true"
};
// Creating a screen object.
ECommerceScreen screen = ECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "даниссимо кленовый сироп", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Акции", "Красная цена"] // Optional.
    );
ECommerceAmount amount =
    ECommerceAmount(amount: Decimal.parse('4.53'), currency: "USD");
// Creating an actualPrice object.
ECommercePrice actualPrice =
    ECommercePrice(fiat: amount, internalComponents: [
  // Optional.
  ECommerceAmount(amount: Decimal.parse('30_570_000'), currency: "wood"),
  ECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
  ECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
]);
// Creating an originalPrice object.
ECommercePrice originalPrice = ECommercePrice(
    fiat: ECommerceAmount(amount: Decimal.parse('5.78'), currency: "USD"),
    internalComponents: [
      // Optional.
      ECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
      ECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
      ECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
    ]);
// Creating a product object.
ECommerceProduct product = ECommerceProduct(
    sku: "779213",
    name: "Продукт творожный «Даниссимо» 5.9%, 130 г.", // Optional.
    actualPrice: actualPrice, // Optional.
    originalPrice: originalPrice, // Optional.
    promocodes: ["BT79IYX", "UT5412EP"], // Optional.
    payload: payload, // Optional.
    categoriesPath: [
      "Продукты",
      "Молочные продукты",
      "Йогурты"
    ] // Optional.
    );
ECommerceEvent showProductDetailsEvent =
    ECommerce.showProductDetailsEvent(product, screen);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key")
    .reportECommerce(showProductDetailsEvent);
Добавление или удаление товара из корзины
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true"
};
// Creating a screen object.
ECommerceScreen screen = ECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "даниссимо кленовый сироп", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Акции", "Красная цена"] // Optional.
    );
ECommerceAmount amount =
    ECommerceAmount(amount: Decimal.parse('4.53'), currency: "USD");
// Creating an actualPrice object.
ECommercePrice actualPrice =
    ECommercePrice(fiat: amount, internalComponents: [
  // Optional.
  ECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
  ECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
  ECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
]);
// Creating an originalPrice object.
ECommercePrice originalPrice = ECommercePrice(
    fiat: ECommerceAmount(amount: Decimal.parse('5.78'), currency: "USD"),
    internalComponents: [
      // Optional.
      ECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
      ECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
      ECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
    ]);
// Creating a product object.
ECommerceProduct product = ECommerceProduct(
    sku: "779213",
    name: "Продукт творожный «Даниссимо» 5.9%, 130 г.", // Optional.
    actualPrice: actualPrice, // Optional.
    originalPrice: originalPrice, // Optional.
    promocodes: ["BT79IYX", "UT5412EP"], // Optional.
    payload: payload, // Optional.
    categoriesPath: [
      "Продукты",
      "Молочные продукты",
      "Йогурты"
    ] // Optional.
    );
ECommerceReferrer referrer = ECommerceReferrer(
    type: "button", // Optional.
    identifier: "76890", // Optional.
    screen: screen // Optional.
    );
// Creating a cartItem object.
ECommerceCartItem addedItems1 = ECommerceCartItem(
    product: product,
    revenue: actualPrice,
    quantity: Decimal.parse("1.0"),
    referrer: referrer // Optional.
    );
ECommerceEvent addCartItemEvent = ECommerce.addCartItemEvent(addedItems1);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key").reportECommerce(addCartItemEvent);
ECommerceEvent removeCartItemEvent =
    ECommerce.removeCartItemEvent(addedItems1);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key")
    .reportECommerce(removeCartItemEvent);
Начало оформления и завершение покупки
Map<String, String> payload = {
  "configuration": "landscape",
  "full_screen": "true"
};
// Creating a screen object.
ECommerceScreen screen = ECommerceScreen(
    name: "ProductCardActivity", // Optional.
    searchQuery: "даниссимо кленовый сироп", // Optional.
    payload: payload, // Optional.
    categoriesPath: ["Акции", "Красная цена"] // Optional.
    );
ECommerceAmount amount =
    ECommerceAmount(amount: Decimal.parse('4.53'), currency: "USD");
// Creating an actualPrice object.
ECommercePrice actualPrice =
    ECommercePrice(fiat: amount, internalComponents: [
  // Optional.
  ECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
  ECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
  ECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
]);
// Creating an originalPrice object.
ECommercePrice originalPrice = ECommercePrice(
    fiat: ECommerceAmount(amount: Decimal.parse('5.78'), currency: "USD"),
    internalComponents: [
      // Optional.
      ECommerceAmount(amount: Decimal.parse('30570000'), currency: "wood"),
      ECommerceAmount(amount: Decimal.parse('26.89'), currency: "iron"),
      ECommerceAmount(amount: Decimal.parse('5.1'), currency: "gold"),
    ]);
// Creating a product object.
ECommerceProduct product = ECommerceProduct(
    sku: "779213",
    name: "Продукт творожный «Даниссимо» 5.9%, 130 г.", // Optional.
    actualPrice: actualPrice, // Optional.
    originalPrice: originalPrice, // Optional.
    promocodes: ["BT79IYX", "UT5412EP"], // Optional.
    payload: payload, // Optional.
    categoriesPath: [
      "Продукты",
      "Молочные продукты",
      "Йогурты"
    ] // Optional.
    );
ECommerceReferrer referrer = ECommerceReferrer(
    type: "button", // Optional.
    identifier: "76890", // Optional.
    screen: screen // Optional.
    );
// Creating a cartItem object.
ECommerceCartItem addedItems1 = ECommerceCartItem(
    product: product,
    revenue: actualPrice,
    quantity: Decimal.parse("1.0"),
    referrer: referrer // Optional.
    );
// Creating an order object.
ECommerceOrder order = ECommerceOrder(
    identifier: "88528768",
    items: [addedItems1],
    payload: payload // Optional.
    );
ECommerceEvent beginCheckoutEvent = ECommerce.beginCheckoutEvent(order);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key")
    .reportECommerce(beginCheckoutEvent);
ECommerceEvent purchaseEvent = ECommerce.purchaseEvent(order);
// Sending an e-commerce event.
AppMetrica.getReporter("Testing API key").reportECommerce(purchaseEvent);

Шаг 3. Проверьте отчет тестового приложения

Совершите тестовые покупки в приложении. Через некоторое время в интерфейсе AppMetrica проверьте отчет «Анализ покупок». Убедитесь, что ECommerce-события отображаются в отчете. Подробнее об отчете в разделе Анализ покупок.

Шаг 4. Настройте отправку ECommerce на основной API Key

После успешного тестирования настройте отправку ECommerce-событий на основной API key.

Чтобы отправить объект ECommerceEvent на основной API key, используйте метод AppMetrica.reportECommerce(ECommerceEvent event):

...
// Sending an e-commerce event.
AppMetrica.reportECommerce(ecommerceEvent);

Отправка Ad Revenue на Flutter

В AppMetrica можно передавать данные о выручке от показов рекламы (Ad Revenue).

Шаг 1. Убедитесь, что SDK активирован

Пример активации:

AppMetricaConfig config = AppMetricaConfig("API_KEY");
AppMetrica.activate(config);

Шаг 2. Настройте отправку Ad Revenue

  1. Создайте объект класса AdRevenue.

     Map<String, String> adRevenuePayload = {
       "payload_key_1": "payload_value_1",
       "payload_key_2": "payload_value_2"
     };
    
     AdRevenue adRevenue = AdRevenue(
         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. Отправьте объект AdRevenue используя метод reportAdRevenue(AdRevenue).

    AppMetrica.reportAdRevenue(adRevenue);
    

Шаг 3. Убедитесь, что Ad Revenue отображается в отчетах

  1. Совершите просмотры рекламы в приложении.

  2. Убедитесь, что в отчете Revenue количество событий Ad Revenue соответствует количеству просмотров рекламы.

Получение различных идентификаторов AppMetrica SDK

Чтобы получить различные идентификаторы AppMetrica SDK (DeviceId, DeviceIdHash, UUID) используйте метод requestStartupParams(). Для получения appmetrica_device_id нужно запрашивать DeviceIdHash.

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)
    });

Если вы не нашли ответ на свой вопрос, то вы можете задать его через форму обратной связи. Пожалуйста, опишите возникшую проблему как можно подробнее. Если возможно, приложите скриншот.

Написать в службу поддержки