Usage examples

Library initialization with the extended configuration

To initialize the library with the extended startup configuration, create an AppMetricaConfig instance with appropriate settings and activate the library using the AppMetrica.activate(config: AppMetricaConfig) method. For example, you can use the extended configuration to enable/disable logging, set session timeouts, pass parameters for tracking pre-installed apps, and more.

Extended configuration settings take effect immediately upon library initialization.

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

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

To configure the library while the app is running, use the AppMetrica class methods.

Using the library to send device location

Note

Sending device location is disabled by default for Android.

To enable sending location data, initialize the library with the configuration where sending device location data is enabled. To do this, set the locationTracking property to true when creating an extended library configuration.

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

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

To enable sending location data while the app is running, use the AppMetrica.setLocationTracking(enabled: boolean) method:

AppMetrica.setLocationTracking(true);

For more precise locations, add one of the following permissions to the AndroidManifest.xml file:

Setting location manually

Before sending custom information about the device location, make sure that reporting is enabled.

The library determines the device location on its own. To send custom device location data, pass Location to the AppMetrica.setLocation(location?: Location) method.

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

// Determining the location.
const currentLocation: Location = {
  ...
}
// Setting up custom device location data.
AppMetrica.setLocation(currentLocation);

To send custom device location data using the extended configuration, pass the Location instance to the location?: Location property when creating an extended library configuration.

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 up a custom device location.
  location: currentLocation,
}
// Initializing the AppMetrica SDK.
AppMetrica.activate(config);

To send custom device location data while the app is running, use the AppMetrica.setLocation(location?: Location) method.

AppMetrica.setLocation(currentLocation);

Sending a custom event

To send a custom event with no nested parameters, pass a short name or description of the event to the AppMetrica.reportEvent(eventName: string, attributes?: Record<string, any>) method:

AppMetrica.reportEvent("Updates installed");

Sending a custom event with nested parameters

With the AppMetrica SDK, you can send custom events with nested parameters in JSON format. For this, use the AppMetrica.reportEvent(eventName: string, attributes?: Record<string, any>) method:

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

The AppMetrica web interface displays up to five nesting levels for events. So if an event has six or more levels, only the top five are shown in the report. You can use the Reporting API to export up to ten levels.

For more information about events, see Events.

Sending a custom error message

To send a custom error message, use the AppMetrica.reportError(identifier: string, message: string) method.

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

Errors are grouped by ID. Don't use variable values as grouping IDs. Otherwise, the number of groups increases and it becomes difficult to analyze them.

Sending ProfileId

If you know the user profile ID before initializing the AppMetrica SDK, pass it before initialization (setUserProfileID):

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

Or during initialization with an extended configuration (userProfileID):

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

Otherwise, a user profile is created with the ID appmetrica_device_id.

Warning

AppMetrica doesn't display predefined attributes in the web interface if ProfieId sending isn't configured.

You can update ProfileId at any time by calling setUserProfileID:

AppMetrica.setUserProfileID('your-id');

Sending profile attributes

To send profile attributes, pass the required attributes to an instance of the UserProfile class and send the instance using the AppMetrica.reportUserProfile(userProfile: UserProfile) method. To create profile attributes, use methods of the Attributes class.

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

Sending E-commerce events

For different user actions, there are appropriate types of e-commerce events. To create a specific event type, use the appropriate ECommerce class method.

The examples below show how to send specific types of events:

Opening a page
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: 'danissimo maple syrup',  // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Promos', 'Hot deal'], // Optional.
};
const showScreen = ECommerce.showScreenEvent(screen);
// Sending an e-commerce event.
AppMetrica.reportECommerce(showScreen);
Viewing a product card
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: 'danissimo maple syrup',  // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Promos', 'Hot deal'], // 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: 'Danissimo Сurd Dessert 5.9%, 130 g',  // Optional.
  actualPrice: actualPrice, // Optional.
  originalPrice: originalPrice, // Optional.
  promocodes: ['BT79IYX', 'UT5412EP'],  // Optional.
  payload: payload,    // Optional.
  categoriesPath: ['Groceries', 'Dairy', 'Yogurts']  // Optional.
};
// Sending an E-commerce event.
AppMetrica.reportECommerce(ECommerce.showProductCardEvent(product, screen));
Viewing a product page
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: 'danissimo maple syrup',  // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Promos', 'Hot deal'], // 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: 'Danissimo Сurd Dessert 5.9%, 130 g',  // Optional.
  actualPrice: actualPrice, // Optional.
  originalPrice: originalPrice, // Optional.
  promocodes: ['BT79IYX', 'UT5412EP'],  // Optional.
  payload: payload,    // Optional.
  categoriesPath: ['Groceries', 'Dairy', 'Yogurts']  // Optional.
};

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

const showProductDetails = ECommerce.showProductDetailsEvent(product, referrer);
// Sending an E-commerce event.
AppMetrica.reportECommerce(showProductDetails);
Adding/removing an item to/from the cart
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: 'danissimo maple syrup',  // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Promos', 'Hot deal'], // 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: 'Danissimo Сurd Dessert 5.9%, 130 g',  // Optional.
  actualPrice: actualPrice, // Optional.
  originalPrice: originalPrice, // Optional.
  promocodes: ['BT79IYX', 'UT5412EP'],  // Optional.
  payload: payload,    // Optional.
  categoriesPath: ['Groceries', 'Dairy', 'Yogurts']  // 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);
Starting and completing a purchase
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: 'danissimo maple syrup',  // Optional.
  payload: payload,                          // Optional.
  categoriesPath: ['Promos', 'Hot deal'], // 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: 'Danissimo Сurd Dessert 5.9%, 130 g',  // Optional.
  actualPrice: actualPrice, // Optional.
  originalPrice: originalPrice, // Optional.
  promocodes: ['BT79IYX', 'UT5412EP'],  // Optional.
  payload: payload,    // Optional.
  categoriesPath: ['Groceries', 'Dairy', 'Yogurts']  // 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);

Sending Revenue events

With validation

AppMetrica supports in-app purchase validation for purchases made through the Google Play Billing and StoreKit libraries.

To validate purchases, configure sending the Receipt instance along with Revenue:

  • On Android, use Receipt to send originalJson to receiptData, and to send signature to the signature property.

  • On iOS, configure sending the transactionID and receiptData fields where you implement the transaction completion:

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);
Without validation
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);

Sending Ad Revenue events

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

Create an AdRevenue instance:

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',
};

Send the AdRevenue instance using the AppMetrica.reportAdRevenue(adRevenue: AdRevenue) method:

AppMetrica.reportAdRevenue(adRevenue);

Setting the session timeout duration

By default, the session timeout is 10 seconds. This is the minimum allowed value for the sessionTimeout property.

To change the timeout duration, pass the value in seconds to the sessionTimeout method when creating an extended library configuration.

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

Setting the app version

To specify the app version programmatically, pass the app version to the appVersion property when creating an extended library configuration.

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

Where 1.0 is the app version.

Determining the library's API level (Android)

To determine the API level of the library from the application code, use the AppMetrica.getLibraryApiLevel() method.

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

Determining the library's version

To determine the library version from the application code, use the AppMetrica.getLibraryVersion() method:

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

Deeplink opens are tracked by default. You can disable this by using an extended configuration:

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

If needed, you can manually send information about deeplink-triggered app opens to AppMetrica using the reportAppOpen() method:

AppMetrica.reportAppOpen(deeplink);

See also How to create a remarketing campaign in AppMetrica.

Tracking new users

By default, the user is counted as a new user when the app is opened for the first time. If the AppMetrica SDK connects to an app that already has active users, to obtain valid statistics, you can set up tracking of both new and old users. To do this, initialize the AppMetrica SDK using an extended startup configuration, 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);

Disabling and enabling sending statistics

If you need to obtain user consent before sending statistical data, initialize the library with the statistics sending option disabled. To do this, pass false to the statisticsSending property when creating an extended library configuration.

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

After the user consents to statistics sending (for example, through app settings or by giving their permission during the first app launch), use the AppMetrica.setDataSendingEnabled(true) method to enable statistics sending:

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

Alert example

You can use any text to inform users of statistics collection. For example:

This app uses the AppMetrica analytical service provided by YANDEX LLC, ulitsa Lva Tolstogo 16, Moscow, Russia 119021 (hereinafter referred to as Yandex) based on the Terms of Use.

AppMetrica analyzes app usage data, including information about the device it is running on, install source, conversions, and statistics of your activity, for the purposes of product analytics, ad campaign optimization, and troubleshooting. The data collected in this manner cannot be used to identify you.

The depersonalized information about your use of this app collected by AppMetrica tools will be transferred to Yandex and stored on Yandex servers in the EU and the Russian Federation. Yandex will process this information to provide you with app usage statistics, generate reports for us on app performance, and deliver other services.

Getting AppMetrica SDK IDs

To get AppMetrica SDK IDs (DeviceId, DeviceIdHash, UUID), use the requestStartupParams() method. To get the appmetrica_device_id, make sure to request the 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);

If you didn't find the answer you were looking for, you can use the feedback form to submit your question. Please describe the problem in as much detail as possible. Attach a screenshot if possible.

Contact support
Previous
Methods
Next
About push campaigns