Methods

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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