Примеры использования методов
- Инициализация библиотеки с расширенной конфигурацией
- Отправка местоположения устройства библиотекой
- Установка местоположения вручную
- Отправка собственного события
- Отправка собственного события с вложенными параметрами
- Отправка собственного сообщения об ошибке
- Отправка ProfileId
- Отправка атрибутов профиля
- Отправка ECommerce-событий
- Отправка Revenue
- Установка длительности таймаута сессии
- Установка версии приложения
- Определение уровня API библиотеки (Android)
- Определение версии библиотеки
- Отслеживание открытий приложения с помощью deeplink
- Учет новых пользователей
- Отключение и включение отправки статистики
- Получение различных идентификаторов AppMetrica SDK
Инициализация библиотеки с расширенной конфигурацией
Чтобы инициализировать библиотеку с расширенной стартовой конфигурацией, создайте объект типа 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);
Установка длительности таймаута сессии
По умолчанию длительность таймаута сессии равна 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);
Если вы не нашли ответ на свой вопрос, то вы можете задать его через форму обратной связи. Пожалуйста, опишите возникшую проблему как можно подробнее. Если возможно, приложите скриншот.