Methods

Types

// This type contains the extended configuration for library initialization.
export type AppMetricaConfig = {
  apiKey: string,
  appVersion?: string,
  crashReporting?: boolean,
  firstActivationAsUpdate?: boolean,
  location: Location,
  locationTracking?: boolean,
  logs?: boolean,
  sessionTimeout?: number,
  statisticsSending?: boolean,
  preloadInfo?: PreloadInfo,
  appOpenTrackingEnabled?: boolean,
  maxReportsInDatabaseCount?: number,
  nativeCrashReporting?: boolean, // Android only.
  activationAsSessionStart?: boolean, // iOS only.
  sessionsAutoTracking?: boolean,
  userProfileID?: string,
  errorEnvironment?: Record<string, string | undefined>,
  appEnvironment?: Record<string, string | undefined>,
  maxReportsCount?: number,
  dispatchPeriodSeconds?: number,
}

// This type contains information for tracking pre-installed apps.
export type PreloadInfo = {
  trackingId: string,
  additionalInfo?: Record<string, string>,
}

// This type contains information about the device's location.
export type Location = {
  latitude: number,
  longitude: number,
  altitude?: number,
  accuracy?: number,
  course?: number,
  speed?: number,
  timestamp?: number,
}

// This type contains possible errors from the requestStartupParams() method.
export type StartupParamsReason = 'UNKNOWN' | 'NETWORK' | 'INVALID_RESPONSE';

// This type contains IDs that were obtained using the requestStartupParams() method.
export type StartupParams = {
  deviceIdHash?: string,
  deviceId?: string,
  uuid?: string,
}

// This type is a callback passed to the requestStartupParams() method.
type StartupParamsCallback = (
  params?: StartupParams,
  reason?: StartupParamsReason
) => void

// This type contains information about the screen where the E-commerce event occurs.
export type ECommerceScreen = {
  name: string,
  searchQuery?: string,
  payload?: Map<string, string>,
  categoriesPath?: Array<string>,
}

// This type contains the currency and cost data.
export type ECommerceAmount = {
  amount: number | string,
  unit: string,
}

// This type contains the price information.
export type ECommercePrice = {
  amount: ECommerceAmount,
  internalComponents?: Array<ECommerceAmount>,
}

// This type contains information about a specific product.
export type ECommerceProduct = {
  sku: string,
  name?: string,
  actualPrice?: ECommercePrice,
  originalPrice?: ECommercePrice,
  promocodes?: Array<string>,
  categoriesPath?: Array<string>,
  payload?: Map<string, string>,
}

// This type contains data about the referrer that brought the user to the product.
export type ECommerceReferrer = {
  type?: string,
  identifier?: string,
  screen?: ECommerceScreen,
}

// This type contains data about a cart item, its price and quantity.
export type ECommerceCartItem = {
  product: ECommerceProduct,
  price: ECommercePrice,
  quantity: number | string,
  referrer?: ECommerceReferrer,
}

// This type contains information about an order.
export type ECommerceOrder = {
  orderId: string,
  products: Array<ECommerceCartItem>,
  payload?: Map<string, string>,
}

// This type is used for sending in-app purchase data from the app. Contains revenue data.
export type Revenue = {
  price: number,
  currency: string,
  productID?: string,
  quantity?: number,
  payload?: string,
  receipt?: Receipt,
}

// This type is used for validating in-app purchases.
export type Receipt = {
  transactionID?: string,
  receiptData?: string,
  signature?: string,
}

// This type contains ad revenue  information.
export type AdRevenue = {
  price: number | string,
  currency: string,
  payload?: Map<string, string>,
  adNetwork?: string,
  adPlacementID?: string,
  adPlacementName?: string,
  adType?: AdType,
  adUnitID?: string,
  adUnitName?: string,
  precision?: string,
}

// Possible values for GenderAttribute
export type UserProfileGender = 'male' | 'female' | 'other';

// Extended reporter configuration.
export type ReporterConfig = {
  apiKey: string,
  logs?: boolean,
  maxReportsInDatabaseCount?: number,
  sessionTimeout?: number,
  dataSendingEnabled?: boolean,
  appEnvironment?: Record<string, string | undefined>,
  dispatchPeriodSeconds?: number,
  userProfileID?: string,
  maxReportsCount?: number,
}

// Possible errors from the requestDeferredDeeplink() and requestDeferredDeeplinkParameters() methods.
export type DeferredDeeplinkError = 'NO_REFERRER' | 'NOT_A_FIRST_LAUNCH' | 'PARSE_ERROR' | 'UNKNOWN';

Enums

// This type contains supported ad types for sending AdRevenue data.
export enum AdType {
  NATIVE,
  BANNER,
  MREC,
  INTERSTITIAL,
  REWARDED,
  OTHER,
}

Classes

AppMetrica

The main class used for interacting with the library.

// Initializes the library with the extended configuration.
activate(config: AppMetricaConfig)

// Returns the current version of the library.
async getLibraryVersion(): string

// Reports that the current session has been paused.
pauseSession()

// Reports that the app has been opened via a deeplink.
reportAppOpen(deeplink?: string = null)

// Reports a custom event.
reportEvent(eventName: string, attributes?: Record<string, any>)

// Reports errors.
reportError(identifier: string, message: string)

// Reports errors without an ID.
reportErrorWithoutIdentifier(message: string | undefined, error: Error)

// Reports crashes.
reportUnhandledException(error: Error)

// Requests various IDs from the AppMetrica SDK.
requestStartupParams(listener: StartupParamsCallback, identifiers: Array<string>)

// Reports whether a session has been resumed or a new one has started after a timeout.
resumeSession()

// This method sends events stored in the buffer.
sendEventsBuffer()

// This method sends the device's location data.
setLocation(location?: Location)

// This method enables/disables the collection of device location data.
setLocationTracking(enabled: boolean)

// This method enables/disables sending data to AppMetrica.
setDataSendingEnabled(enabled: boolean)

// This method assigns a profile ID.
setUserProfileID(userProfileID?: string)

// This is an Android-only method. It returns the library's API level.
async getLibraryApiLevel(): number

// Sends E-commerce events.
reportECommerce(event: ECommerceEvent)

// Sends in-app purchases.
reportRevenue(revenue: Revenue)

// Sends AdRevenue.
reportAdRevenue(adRevenue: AdRevenue)

// Sends user profiles.
reportUserProfile(userProfile: UserProfile)

// Clears all key-value data associated with all future events.
clearAppEnvironment()

// Sets a key-value pair associated with all future events.
putAppEnvironmentValue(key: string, value?: string)

// Returns an object implementing IReporter for the specified application API key.
getReporter(apiKey: string)

// Activates the reporter with the extended configuration.
activateReporter(config: ReporterConfig)

// Returns the device ID or null.
async getDeviceId()

// Returns the install ID or null.
async getUuid()

// Requests a deferred deeplink. Deferred deeplinks become available after receiving the Google Play installation referrer.
// The referrer is typically available shortly after the app's first launch.
// Once the referrer is received, the deferred deeplink gets passed to DeferredDeeplinkListener.onSuccess(deeplink: string).
// Any errors get passed to DeferredDeeplinkListener.onFailure(error: DeferredDeeplinkError, referrer?: string).
requestDeferredDeeplink(listener: DeferredDeeplinkListener)

// Requests parameters of the deferred deeplink. Parameters become available after receiving the Google Play installation referrer.
// The referrer is typically available shortly after the app's first launch.
// Once the referrer is received, deferred deeplink parameters get passed to DeferredDeeplinkParametersListener.onSuccess(parameters: Record<string, string>).
// Any errors get passed to DeferredDeeplinkParametersListener.onFailure: (error: DeferredDeeplinkError, referrer?: string).
requestDeferredDeeplinkParameters(listener: DeferredDeeplinkParametersListener)

E-commerce

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

For more information about sending E-commerce events, see E-commerce.

// Returns ECommerceEvent for sending a “product card view” event.
showProductCardEvent(product: ECommerceProduct, screen: ECommerceScreen): ECommerceEvent

// Returns ECommerceEvent for sending a “product page view” event.
showProductDetailsEvent(product: ECommerceProduct, referrer?: ECommerceReferrer): ECommerceEvent

// Returns ECommerceEvent for sending an “add item to cart” event.
addCartItemEvent(item: ECommerceCartItem): ECommerceEvent

// Returns ECommerceEvent for sending a “remove item from cart” event.
removeCartItemEvent(item: ECommerceCartItem): ECommerceEvent

// Returns ECommerceEvent for sending a ”begin checkout” event.
beginCheckoutEvent(order: ECommerceOrder): ECommerceEvent

// Returns ECommerceEvent for sending a “purchase complete” event.
purchaseEvent(order: ECommerceOrder): ECommerceEvent

To learn more about the API methods and AppMetrica integration into your app, see the Android and iOS sections in our documentation.

UserProfile

A class for storing a user profile. Learn more.

// Applies a user attribute to UserProfile
apply(attribute: UserProfileUpdate): UserProfile

Attributes

A class for creating profile attributes. Learn more.

// Creates a predefined attribute for birth date / age.
birthDate(): BirthDateAttribute

// Creates a predefined gender attribute.
gender(): GenderAttribute

// Creates a predefined name attribute.
userName(): NameAttribute

// Creates a predefined notification status attribute.
notificationsEnabled(): NotificationsEnabledAttribute

// Creates a custom attribute of the bool type.
customBoolean(key: string): BooleanAttribute

// Creates a custom attribute of the tag type.
customCounter(key: string): CounterAttribute

// Creates a custom attribute of the number type.
customNumber(key: string): NumberAttribute

// Creates a custom attribute of the string type.
customString(key: string): StringAttribute

BirthDateAttribute

A class for updating the age or date of birth in a user profile.

// Updates the attribute value.
withAge(age: number): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withAgeIfUndefined(age: number): UserProfileUpdate

// Updates the attribute value.
withYear(year: number): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withYearIfUndefined(year: number): UserProfileUpdate

// Updates the attribute value.
withMonth(year: number, month: number): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withMonthIfUndefined(year: number, month: number): UserProfileUpdate

// Updates the attribute value.
withDay(year: number, month: number, day: number): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withDayIfUndefined(year: number, month: number, day: number): UserProfileUpdate

// Updates the attribute value.
withDate(date: Date): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withDateIfUndefined(date: Date): UserProfileUpdate

// Resets the attribute value.
withValueReset(): UserProfileUpdate

BooleanAttribute

A class for updating the value of a boolean attribute.

// Updates the attribute value.
withValue(value: boolean): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withValueIfUndefined(value: boolean): UserProfileUpdate

// Resets the attribute value.
withValueReset(): UserProfileUpdate

CounterAttribute

A class for updating the value of the tag type attribute.

// Updates the attribute value.
withDelta(delta: number): UserProfileUpdate

GenderAttribute

A class for updating the gender in a user profile.

// Updates the attribute value.
withValue(gender: UserProfileGender): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withValueIfUndefined(gender: UserProfileGender): UserProfileUpdate

// Resets the attribute value.
withValueReset(): UserProfileUpdate

NameAttribute

A class for updating the name in a user profile.

// Updates the attribute value.
withValue(value: string): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withValueIfUndefined(value: string): UserProfileUpdate

// Resets the attribute value.
withValueReset(): UserProfileUpdate

NotificationsEnabledAttribute

A class for updating the notification status in a user profile.

// Updates the attribute value.
withValue(value: boolean): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withValueIfUndefined(value: boolean): UserProfileUpdate

// Resets the attribute value.
withValueReset(): UserProfileUpdate

NumberAttribute

A class for updating the value of a numeric attribute.

// Updates the attribute value.
withValue(value: number): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withValueIfUndefined(value: number): UserProfileUpdate

// Resets the attribute value.
withValueReset(): UserProfileUpdate

StringAttribute

A class for updating the value of a string attribute.

// Updates the attribute value.
withValue(value: string): UserProfileUpdate

// Updates the attribute value if it wasn't set earlier.
withValueIfUndefined(value: string): UserProfileUpdate

// Resets the attribute value.
withValueReset(): UserProfileUpdate

Interfaces

UserProfileUpdate

Contains information about user attribute updates.

Created using the Attributes class methods and passed to the UserProfile.apply method.

IReporter

Use this interface to send data to additional API keys.
Get the implementation using the AppMetrica.getReporter(apiKey: string) method. To activate a reporter with extended configuration, call AppMetrica.activateReporter(config: ReporterConfig) before the first call to AppMetrica.getReporter(apiKey: string) with the same API key.

  // Passes errors through the reporter.
  reportError(identifier: string, message?: string, _reason?: Error | Object)

  // Passes errors without an ID.
  reportErrorWithoutIdentifier(message: string | undefined, error: Error)

  // Sends crashes.
  reportUnhandledException(error: Error)

  // Sends a custom event.
  reportEvent(eventName: string, attributes?: Record<string, any>)

  // Reports that the current session has been paused.
  pauseSession()

  // Reports whether a session has been resumed or a new one has started after a timeout.
  resumeSession()

  // Sends events stored in the buffer.
  sendEventsBuffer()

  // Clears all key-value data associated with all future events.
  clearAppEnvironment()

  // Sets a key-value pair associated with all future events.
  putAppEnvironmentValue(key: string, value?: string)

  // Assigns a profile ID.
  setUserProfileID(userProfileID?: string)

  //  Enables or disables sending data to AppMetrica.
  setDataSendingEnabled(enabled: boolean)

  // Sends user profiles.
  reportUserProfile(userProfile: UserProfile)

  // Sends AdRevenue.
  reportAdRevenue(adRevenue: AdRevenue)

  // Sends E-commerce events.
  reportECommerce(event: ECommerceEvent)

  // Sends in-app purchases.
  reportRevenue(revenue: Revenue)

DeferredDeeplinkListener

Listener for receiving deferred deeplinks. Pass its implementation to the requestDeferredDeeplink(listener: DeferredDeeplinkListener) method.

// Receives the deferred deeplink
onSuccess(deeplink: string)

// Handles errors when receiving deferred deeplinks
onFailure(error: DeferredDeeplinkError, referrer?: string)

DeferredDeeplinkParametersListener

Listener for receiving deferred deeplink parameters. Pass its implementation to the requestDeferredDeeplinkParameters(listener: DeferredDeeplinkParametersListener) method.

// Receives deferred deeplink parameters
onSuccess(parameters: Record<string, string>)

// Handles errors when receiving deferred deeplink parameters
onFailure(error: DeferredDeeplinkError, referrer?: string)

See also

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