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

Инициализация библиотеки с расширенной конфигурацией

Чтобы инициализировать библиотеку с расширенной стартовой конфигурацией, создайте объект типа AppMetricaConfig с необходимыми настройками и активируйте библиотеку с помощью метода AppMetrica.activate(config: AppMetricaConfig). С помощью расширенной конфигурации можно, например, включить/отключить логирование, установить таймаут сессии, передать параметры для отслеживания предустановленных приложений и т. д.

Настройки расширенной конфигурации применяются с момента инициализации библиотеки.

import AppMetrica, {AppMetricaConfig} from '@appmetrica/react-native-analytics';

const config: AppMetricaConfig = {
  apiKey: API_KEY,
  firstActivationAsUpdate: false,
  logs: true,
  sessionTimeout: 20,
}
AppMetrica.activate(config);

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

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

Примечание

Для Android отправка местоположения устройства по умолчанию отключена.

Чтобы включить отправку, инициализируйте библиотеку с конфигурацией, в которой отправка информации о местоположении устройства включена. Для этого укажите true в свойство locationTracking при создании расширенной конфигурации библиотеки.

import AppMetrica, {AppMetricaConfig} from '@appmetrica/react-native-analytics';

const config: AppMetricaConfig = {
  apiKey: API_KEY,
  locationTracking: true,
}
AppMetrica.activate(config);

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

AppMetrica.setLocationTracking(true);

Для более точного определения местоположения добавьте в файл AndroidManifest.xml одно из следующих разрешений:

android.permission.ACCESS_COARSE_LOCATION — для приблизительного определения.
android.permission.ACCESS_FINE_LOCATION — для точного определения.

Установка местоположения вручную

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

Библиотека определяет местоположение устройства самостоятельно. Чтобы отправить собственную информацию о местоположении устройства, передайте Location в метод AppMetrica.setLocation(location?: Location).

import AppMetrica from '@appmetrica/react-native-analytics';

// Determining the location.
const currentLocation: Location = {
  ...
}
// Setting your own location information of the device.
AppMetrica.setLocation(currentLocation);

Чтобы отправить собственную информацию о местоположении устройства с помощью расширенной конфигурации, передайте объект типа Location в свойство location?: Location при создании расширенной конфигурации библиотеки.

import AppMetrica, {AppMetricaConfig, Location} from '@appmetrica/react-native-analytics';

// Determining the location.
const currentLocation: Location = {
  ...
}
// Creating an extended library configuration.
const config: AppMetricaConfig = {
  apiKey: API_KEY,
  // Set your own location information of the device.
  location: currentLocation,
}
// Initializing the AppMetrica SDK.
AppMetrica.activate(config);

Чтоб отправить собственную информацию о местоположении устройства в процессе работы приложения используйте метод AppMetrica.setLocation(location?: Location)

AppMetrica.setLocation(currentLocation);

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

Чтобы отправить собственное событие без вложенных параметров, передайте короткое название или описание события в метод AppMetrica.reportEvent(eventName: string, attributes?: Record<string, any>):

AppMetrica.reportEvent("Updates installed");

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

AppMetrica SDK позволяет отправлять собственные события с вложенными параметрами, которые могут быть заданы в формате JSON. Для этого спользуйте метод AppMetrica.reportEvent(eventName: string, attributes?: Record<string, any>):

AppMetrica.reportEvent('My event', {foo: 'bar'});

Веб-интерфейс AppMetrica отображает до пяти уровней вложенности события. Если событие содержит шесть уровней и более, в отчете отобразятся пять верхних. С помощью API отчетов можно выгрузить до десяти уровней.

Подробнее о событиях в разделе События.

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

Чтобы отправить собственное сообщение об ошибке, используйте метод AppMetrica.reportError(identifier: string, message: string).

try {
...
} catch (e: Error) {
  AppMetrica.reportError('my error', e.message);
}

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

Отправка ProfileId

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

AppMetrica.setUserProfileID('your-id');
AppMetrica.activate({apiKey: 'API_KEY'});

Или во время инициализации с расширенной конфигурацией (userProfileID):

AppMetrica.activate({
    apiKey: 'API_KEY',
    userProfileID: 'your-id',
});

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

Важно

Если отправка ProfileId не настроена, предопределенные атрибуты не отображаются в веб-интерфейсе.

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

AppMetrica.setUserProfileID('your-id');

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

Чтобы отправить атрибуты профиля, передайте в объект UserProfile необходимые атрибуты и отправьте этот объект с помощью метода AppMetrica.reportUserProfile(userProfile: UserProfile). Атрибуты профиля создаются с помощью методов класса Attributes.

import AppMetrica, {Attributes, UserProfile} from '@appmetrica/react-native-analytics';

// Creating the UserProfile instance.
const userProfile = new UserProfile()
  // Updating predefined attributes.
  .apply(Attributes.userName().withValue('John'))
  .apply(Attributes.gender().withValue('male'))
  .apply(Attributes.birthDate().withAge(24))
  .apply(Attributes.notificationsEnabled().withValue(false))
  // Updating custom attributes.
  .apply(Attributes.customString('string_attribute').withValue('string'))
  .apply(Attributes.customNumber('number_attribute').withValue(55.0))
  .apply(Attributes.customCounter('counter_attribute').withDelta(1.0))
  .apply(Attributes.customBoolean('boolean_attribute').withValue(true));

// Setting the ProfileID using the method of the AppMetrica class.
AppMetrica.setUserProfileID('your-id');

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

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

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

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

Открытие страницы

import AppMetrica, {
  ECommerce,
  ECommerceScreen,
} from '@appmetrica/react-native-analytics';

const payload: Record<string, string> = {
  configuration: 'landscape',
  full_screen: 'true',
};
// Creating a screen object.
const screen: ECommerceScreen = {
  name: 'ProductCardActivity',               // Optional.
  searchQuery: 'даниссимо кленовый сироп',   // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Акции', 'Красная цена'], // Optional.
};
const showScreen = ECommerce.showScreenEvent(screen);
// Sending an e-commerce event.
AppMetrica.reportECommerce(showScreen);

Просмотр карточки товара

import AppMetrica, {
  ECommerce,
  ECommerceAmount,
  ECommercePrice,
  ECommerceProduct,
  ECommerceScreen,
} from '@appmetrica/react-native-analytics';

const payload: Record<string, string> = {
  configuration: 'landscape',
  full_screen: 'true',
};
// Creating a screen object.
const screen: ECommerceScreen = {
  name: 'ProductCardActivity',               // Optional.
  searchQuery: 'даниссимо кленовый сироп',   // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Акции', 'Красная цена'], // Optional.
};
const amount: ECommerceAmount = {
  amount: 4.53,
  unit: 'USD',
};
// Creating an actualPrice object.
const actualPrice: ECommercePrice = {
  amount: amount,
  internalComponents: [  // Optional.
    {
      amount: 30570000,
      unit: 'wood',
    },
    {
      amount: 26.89,
      unit: 'iron',
    },
    {
      amount: 5.1,
      unit: 'gold',
    },
  ],
};
// Creating an originalPrice object.
const originalPrice: ECommercePrice = {
  amount: {amount: 5.78, unit: 'USD'},
  internalComponents: [  // Optional.
    {
      amount: 30570000,
      unit: 'wood',
    },
    {
      amount: 26.89,
      unit: 'iron',
    },
    {
      amount: 5.1,
      unit: 'gold',
    },
  ],
};
// Creating a product object.
const product: ECommerceProduct = {
  sku: '779213',
  name: 'Продукт творожный «Даниссимо» 5.9%, 130 г.',  // Optional.
  actualPrice: actualPrice, // Optional.
  originalPrice: originalPrice, // Optional.
  promocodes: ['BT79IYX', 'UT5412EP'],  // Optional.
  payload: payload,    // Optional.
  categoriesPath: ['Продукты', 'Молочные продукты', 'Йогурты'],  // Optional.
};
// Sending an e-commerce event.
AppMetrica.reportECommerce(ECommerce.showProductCardEvent(product, screen));

Просмотр страницы товара

import AppMetrica, {
  ECommerce,
  ECommerceAmount,
  ECommercePrice,
  ECommerceProduct,
  ECommerceReferrer,
  ECommerceScreen,
} from '@appmetrica/react-native-analytics';

const payload: Record<string, string> = {
  configuration: 'landscape',
  full_screen: 'true',
};
// Creating a screen object.
const screen: ECommerceScreen = {
  name: 'ProductCardActivity',               // Optional.
  searchQuery: 'даниссимо кленовый сироп',   // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Акции', 'Красная цена'], // Optional.
};

const amount: ECommerceAmount = {
  amount: 4.53,
  unit: 'USD',
};
// Creating an actualPrice object.
const actualPrice: ECommercePrice = {
  amount: amount,
  internalComponents: [  // Optional.
    {
      amount: 30570000,
      unit: 'wood',
    },
    {
      amount: 26.89,
      unit: 'iron',
    },
    {
      amount: 5.1,
      unit: 'gold',
    },
  ],
};
// Creating an originalPrice object.
const originalPrice: ECommercePrice = {
  amount: {amount: 5.78, unit: 'USD'},
  internalComponents: [  // Optional.
    {
      amount: 30570000,
      unit: 'wood',
    },
    {
      amount: 26.89,
      unit: 'iron',
    },
    {
      amount: 5.1,
      unit: 'gold',
    },
  ],
};
// Creating a product object.
const product: ECommerceProduct = {
  sku: '779213',
  name: 'Продукт творожный «Даниссимо» 5.9%, 130 г.',  // Optional.
  actualPrice: actualPrice, // Optional.
  originalPrice: originalPrice, // Optional.
  promocodes: ['BT79IYX', 'UT5412EP'],  // Optional.
  payload: payload,    // Optional.
  categoriesPath: ['Продукты', 'Молочные продукты', 'Йогурты'],  // Optional.
};

const referrer: ECommerceReferrer = {
  type: 'button',
  identifier: '76890',
  screen: screen,
};

const showProductDetails = ECommerce.showProductDetailsEvent(product, referrer);
// Sending an e-commerce event.
AppMetrica.reportECommerce(showProductDetails);

Добавление или удаление товара из корзины

import AppMetrica, {
  ECommerce,
  ECommerceAmount,
  ECommerceCartItem,
  ECommerceOrder,
  ECommercePrice,
  ECommerceProduct,
  ECommerceReferrer,
  ECommerceScreen,
} from '@appmetrica/react-native-analytics';

const payload: Record<string, string> = {
  configuration: 'landscape',
  full_screen: 'true',
};
// Creating a screen object.
const screen: ECommerceScreen = {
  name: 'ProductCardActivity',               // Optional.
  searchQuery: 'даниссимо кленовый сироп',   // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Акции', 'Красная цена'], // Optional.
};

const amount: ECommerceAmount = {
  amount: 4.53,
  unit: 'USD',
};
// Creating an actualPrice object.
const actualPrice: ECommercePrice = {
  amount: amount,
  internalComponents: [  // Optional.
    {
      amount: 30570000,
      unit: 'wood',
    },
    {
      amount: 26.89,
      unit: 'iron',
    },
    {
      amount: 5.1,
      unit: 'gold',
    },
  ],
};
// Creating an originalPrice object.
const originalPrice: ECommercePrice = {
  amount: {amount: 5.78, unit: 'USD'},
  internalComponents: [  // Optional.
    {
      amount: 30570000,
      unit: 'wood',
    },
    {
      amount: 26.89,
      unit: 'iron',
    },
    {
      amount: 5.1,
      unit: 'gold',
    },
  ],
};
// Creating a product object.
const product: ECommerceProduct = {
  sku: '779213',
  name: 'Продукт творожный «Даниссимо» 5.9%, 130 г.',  // Optional.
  actualPrice: actualPrice, // Optional.
  originalPrice: originalPrice, // Optional.
  promocodes: ['BT79IYX', 'UT5412EP'],  // Optional.
  payload: payload,    // Optional.
  categoriesPath: ['Продукты', 'Молочные продукты', 'Йогурты'],  // Optional.
};
// Creating a referrer object.
const referrer: ECommerceReferrer = {
  type: 'button', // Optional.
  identifier: '76890', // Optional.
  screen: screen, // Optional.
};
// Creating a cartItem object.
const ecommerceCartItem: ECommerceCartItem = {
  product: product,
  price: actualPrice,
  quantity: 1.0,
  referrer: referrer, // Optional.
};

const addCartItem = ECommerce.addCartItemEvent(ecommerceCartItem);
// Sending an e-commerce event.
AppMetrica.reportECommerce(addCartItem);

const removeCartItem = ECommerce.removeCartItemEvent(ecommerceCartItem);
// Sending an e-commerce event.
AppMetrica.reportECommerce(removeCartItem);

Начало оформления и завершение покупки

import AppMetrica, {
  ECommerce,
  ECommerceAmount,
  ECommerceCartItem,
  ECommerceOrder,
  ECommercePrice,
  ECommerceProduct,
  ECommerceReferrer,
  ECommerceScreen,
} from '@appmetrica/react-native-analytics';

const payload: Record<string, string> = {
  configuration: 'landscape',
  full_screen: 'true',
};
// Creating a screen object.
const screen: ECommerceScreen = {
  name: 'ProductCardActivity',               // Optional.
  searchQuery: 'даниссимо кленовый сироп',   // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Акции', 'Красная цена'], // Optional.
};

const amount: ECommerceAmount = {
  amount: 4.53,
  unit: 'USD',
};
// Creating an actualPrice object.
const actualPrice: ECommercePrice = {
  amount: amount,
  internalComponents: [  // Optional.
    {
      amount: 30570000,
      unit: 'wood',
    },
    {
      amount: 26.89,
      unit: 'iron',
    },
    {
      amount: 5.1,
      unit: 'gold',
    },
  ],
};
// Creating an originalPrice object.
const originalPrice: ECommercePrice = {
  amount: {amount: 5.78, unit: 'USD'},
  internalComponents: [  // Optional.
    {
      amount: 30570000,
      unit: 'wood',
    },
    {
      amount: 26.89,
      unit: 'iron',
    },
    {
      amount: 5.1,
      unit: 'gold',
    },
  ],
};
// Creating a product object.
const product: ECommerceProduct = {
  sku: '779213',
  name: 'Продукт творожный «Даниссимо» 5.9%, 130 г.',  // Optional.
  actualPrice: actualPrice, // Optional.
  originalPrice: originalPrice, // Optional.
  promocodes: ['BT79IYX', 'UT5412EP'],  // Optional.
  payload: payload,    // Optional.
  categoriesPath: ['Продукты', 'Молочные продукты', 'Йогурты'],  // Optional.
};
// Creating a referrer object.
const referrer: ECommerceReferrer = {
  type: 'button', // Optional.
  identifier: '76890', // Optional.
  screen: screen, // Optional.
};
// Creating a cartItem object.
const ecommerceCartItem: ECommerceCartItem = {
  product: product,
  price: actualPrice,
  quantity: 1.0,
  referrer: referrer, // Optional.
};

const order: ECommerceOrder = {
  orderId: '88528768',
  products: [ecommerceCartItem],
  payload: undefined,
};

const beginCheckout = ECommerce.beginCheckoutEvent(order);
// Sending an e-commerce event.
AppMetrica.reportECommerce(beginCheckout);

const purchase = ECommerce.purchaseEvent(order);
// Sending an e-commerce event.
AppMetrica.reportECommerce(purchase);

Отправка событий Revenue

С валидацией

AppMetrica поддерживает валидацию покупок, которые реализованы с помощью библиотек Google Play Billing и StoreKit.

Чтобы покупки валидировались, настройте отправку объекта Receipt вместе с Revenue:

Для Android в Receipt передавайте originalJson в receiptData и signature в свойство signature.
Для iOS в собственной реализации завершения транзакции настройте отправку полей transactionID и receiptData.

import AppMetrica, {Revenue} from '@appmetrica/react-native-analytics';

const revenue: Revenue = {
  price: 500,
  currency: 'USD',
  productID: '12345',
  quantity: 1,
  payload: JSON.stringify({test: 'test'}),
  receipt: {
    receiptData: purcahse.getOriginalJson(),
    signature: purcahse.getSignature(),
  },
};
AppMetrica.reportRevenue(revenue);

Без валидации

import AppMetrica, {Revenue} from '@appmetrica/react-native-analytics';

const revenue: Revenue = {
  price: 500,
  currency: 'USD',
  productID: '12345',
  quantity: 1,
  payload: JSON.stringify({test: 'test'}),
};
AppMetrica.reportRevenue(revenue);

Отправка событий Ad Revenue

import AppMetrica, {
  AdRevenue,
  AdType
} from '@appmetrica/react-native-analytics';

Создайте объект AdRevenue:

const adRevenue: AdRevenue = {
  price: 0.1,
  currency: 'USD',
  payload: {payload_key_1: 'payload_value_1'},
  adNetwork: 'ad_network',
  adPlacementID: 'ad_placement_id',
  adPlacementName: 'ad_placement_name',
  adType: AdType.NATIVE,
  adUnitID: 'ad_unit_id',
  adUnitName: 'ad_unit_name',
  precision: 'some precision',
};

Отправьте объект AdRevenue с помощью метода AppMetrica.reportAdRevenue(adRevenue: AdRevenue):

AppMetrica.reportAdRevenue(adRevenue);

Установка длительности тайм-аута сессии

По умолчанию длительность тайм-аута сессии равна 10 секундам. Это минимально допустимое значение параметра sessionTimeout.

Чтобы изменить длительность тайм-аута, передайте значение в секундах в метод sessionTimeout при создании расширенной конфигурации библиотеки.

// Creating an extended library configuration.
const config: AppMetricaConfig = {
  apiKey: API_KEY,
  // Setting session timeout.
  sessionTimeout: 15,
};
// Initializing the AppMetrica SDK.
AppMetrica.activate(config);

Установка версии приложения

Чтобы указать версию приложения из кода, передайте версию приложения в свойство appVersion при создании расширенной конфигурации библиотеки.

  // Creating an extended library configuration.
const config: AppMetricaConfig = {
  apiKey: API_KEY,
  // Setting the app version.
  appVersion: '1.0',
};
// Initializing the AppMetrica SDK.
AppMetrica.activate(config);

где 1.0 — версия приложения.

Определение уровня API библиотеки (Android)

Чтобы определить уровень API библиотеки из кода приложения, используйте метод AppMetrica.getLibraryApiLevel().

const [libraryApiLevel, setLibraryApiLevel] = useState('???');
AppMetrica.getLibraryApiLevel().then(level => {
  setLibraryApiLevel(level);
});

Определение версии библиотеки

Чтобы определить версию библиотеки из кода приложения, используйте метод AppMetrica.getLibraryVersion().

const [appMetricaVersion, setAppMetricaVersion] = useState('???');
AppMetrica.getLibraryVersion().then(version => {
  setAppMetricaVersion(version);
});

Отслеживание открытий приложения с помощью deeplink

Отслеживание открытий deeplink работает по умолчанию. Выключить отслеживание можно в расширенной конфигурации:

  // Creating an extended library configuration.
const config: AppMetricaConfig = {
  apiKey: API_KEY,
  appOpenTrackingEnabled: false,
};
// Initializing the AppMetrica SDK.
AppMetrica.activate(config);

При необходимости вы можете вручную отправить в AppMetrica информацию об открытии приложения диплинком методом reportAppOpen():

AppMetrica.reportAppOpen(deeplink);

См. также Как создать ремаркетинг-кампанию в AppMetrica.

Учет новых пользователей

По умолчанию в момент первого запуска приложения все пользователи определяются как новые. Если AppMetrica SDK подключается к приложению, у которого уже есть активные пользователи, то для корректного отслеживания статистики можно настроить учет новых и старых пользователей. Для этого необходимо инициализировать AppMetrica SDK, используя расширенную стартовую конфигурацию AppMetricaConfig:

const isFirstLaunch: Boolean = 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;
}
// Creating an extended library configuration.
const config: AppMetricaConfig = {
  apiKey: API_KEY,
  firstActivationAsUpdate: !isFirstLaunch,
};
// Initializing the AppMetrica SDK.
AppMetrica.activate(config);

Отключение и включение отправки статистики

Если для отправки статистических данных требуется согласие пользователя, необходимо инициализировать библиотеку с отключенной опцией отправки статистики. Для этого передайте значение false в свойство statisticsSending при создании расширенной конфигурации библиотеки.

// Creating an extended library configuration.
const config: AppMetricaConfig = {
  apiKey: API_KEY,
  // Disabling sending data.
  statisticsSending: false,
};
// Initializing the AppMetrica SDK.
AppMetrica.activate(config);

После того как пользователь дал согласие на отправку статистики (например, в настройках приложения или в соглашении при первом открытии), включите отправку статистики с помощью метода AppMetrica.setDataSendingEnabled(true):

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

Пример оповещения

Для информирования пользователей вы можете использовать любой текст. Например:

Это приложение использует сервис аналитики AppMetrica, предоставляемый компанией ООО «ЯНДЕКС», 119021, Россия,Москва, ул. Л. Толстого, 16 (далее — Яндекс) на Условиях использования сервиса.

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

Информация об использовании вами данного приложения, собранная при помощи инструментов AppMetrica, в обезличенном виде будет передаваться Яндексу и храниться на сервере Яндекса в ЕС и Российской Федерации. Яндекс будет обрабатывать эту информацию для предоставления статистики использования вами приложения, составления для нас отчетов о работе приложения, и предоставления других услуг.

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

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

import AppMetrica, {
  DEVICE_ID_HASH_KEY,
  DEVICE_ID_KEY,
  UUID_KEY,
  StartupParams,
  StartupParamsCallback,
  StartupParamsReason,
} from '@appmetrica/react-native-analytics';

const paramsList: Array<string> = [
  DEVICE_ID_HASH_KEY,
  DEVICE_ID_KEY,
  UUID_KEY,
];
const paramsCallback: StartupParamsCallback = (params?: StartupParams, reason?: StartupParamsReason) => {
  // ...
};

AppMetrica.requestStartupParams(paramsCallback, paramsList);

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

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

Была ли статья полезна?

Справочник методов

О push-кампаниях