Adjust React Native SDK

Common errors

• Adjust.modulemap not found

  cause Specific CocoaPods integration issues, often related to caching or incorrect project setup.
  fix This issue was fixed in `v5.0.2`. Ensure you are on `v5.0.2` or higher. If it persists, try cleaning CocoaPods cache (`pod cache clean --all`), deleting `Podfile.lock` and `Pods` directory, then reinstalling pods (`pod install`).

• TypeError: Cannot read property 'PROPERTY_NAME' of null/undefined in Adjust SDK callbacks or data objects.

  cause Occasional `NPE occurrences` (Null Pointer Exceptions) in native code were reported, especially when the app was entering the background, or `type mismatch` in `AdjustPlayStoreSubscription` fields.
  fix Ensure you are on `v5.1.0` or higher to fix background NPEs and `v5.0.4` or higher for `AdjustPlayStoreSubscription` type mismatches. Always add null/undefined checks for properties retrieved from Adjust callback objects, as some fields might legitimately be absent.

• Application Not Responding (ANR) on Android during SDK initialization.

  cause Occasional ANRs while reading install referrer from Shared Preferences during SDK initialization on Android.
  fix This issue was fixed in `v5.0.2`. Upgrade to `react-native-adjust` `v5.0.2` or newer to resolve this problem.

Warnings

• gotcha Always use `AdjustConfig.EnvironmentProduction` for live applications and `AdjustConfig.EnvironmentSandbox` for development/testing. Mixing these can lead to inaccurate data.
  Fix: Ensure `ENVIRONMENT` variable passed to `AdjustConfig` is correct for your build environment (e.g., via `__DEV__` or build flavors).
• breaking When upgrading Adjust native SDKs, especially across major versions, verify that the `react-native-adjust` package is also compatible. While `react-native-adjust` abstracts native changes, significant native API shifts might require an update to the React Native wrapper.
  Fix: Always check the official Adjust documentation and `react-native-adjust` release notes before upgrading native SDKs or `react-native-adjust` itself, especially across major versions. The changelog indicates `Adjust Signature library` updates, which, while internal, could imply breaking changes if not handled correctly by the wrapper.
• gotcha The `index.d.ts` file now explicitly indicates nullable types (e.g., in `AdjustAttribution`). TypeScript users might encounter stricter type checking for optional fields, requiring explicit null checks.
  Fix: Update TypeScript code to handle potentially `null` or `undefined` values for properties that are now marked as nullable in the type definitions.
• gotcha New methods like `getAdidWithTimeout`, `getAttributionWithTimeout`, `resolveLinkWithUrl`, `setStoreInfo` and support for Google LVL/ODM have been added in recent versions. Developers intending to use these features must upgrade their SDK.
  Fix: Upgrade to `react-native-adjust` v5.4.0 or higher to access `setStoreInfo`, Google ODM, and v5.5.0 or higher for timeout-based methods and `resolveLinkWithUrl`.

Install

• npm install react-native-adjust npm
• yarn add react-native-adjust yarn
• pnpm add react-native-adjust pnpm

Imports

• Adjust
  wrong:

  import { Adjust } from 'react-native-adjust';

  correct:

  import Adjust from 'react-native-adjust';

  The primary SDK class is a default export.
• AdjustConfig
  wrong:

  import AdjustConfig from 'react-native-adjust';

  correct:

  import { AdjustConfig } from 'react-native-adjust';

  Configuration object is a named export. It's essential for SDK initialization.
• AdjustEvent
  wrong:

  const AdjustEvent = require('react-native-adjust').AdjustEvent;

  correct:

  import { AdjustEvent } from 'react-native-adjust';

  Used for tracking custom in-app events. Ensure you import it as a named export.
• AdjustAttribution

  import { AdjustAttribution } from 'react-native-adjust';

  Type definition for attribution callback data. Primarily used in TypeScript.

Quickstart

Initializes the Adjust SDK, sets up logging and attribution callbacks, and demonstrates tracking a custom event and retrieving the ADID with a timeout.

import Adjust, { AdjustConfig, AdjustEvent, AdjustLogLevel } from 'react-native-adjust';

const APP_TOKEN = process.env.ADJUST_APP_TOKEN ?? 'YOUR_ADJUST_APP_TOKEN';
const ENVIRONMENT = AdjustConfig.EnvironmentSandbox; // Use EnvironmentProduction for production

const config = new AdjustConfig(APP_TOKEN, ENVIRONMENT);

// Set up a log listener for debugging
config.setLogLevel(AdjustLogLevel.Verbose);
config.setLogDelegate((logLevel, message) => {
  console.log(`[Adjust Log] ${AdjustLogLevel[logLevel]}: ${message}`);
});

// Set an attribution listener
config.setAttributionCallbackListener((attribution) => {
  console.log('Attribution changed:', attribution);
});

// Initialize the SDK
Adjust.create(config);

// Track an event after SDK initialization
const trackPurchaseEvent = (amount: number, currency: string) => {
  const event = new AdjustEvent('YOUR_EVENT_TOKEN'); // Replace with your event token
  event.setRevenue(amount, currency);
  event.setTransactionId('ORDER_XYZ_123'); // Optional: Add transaction ID
  Adjust.trackEvent(event);
  console.log(`Tracked purchase event: ${amount} ${currency}`);
};

// Example usage:
trackPurchaseEvent(19.99, 'USD');

Adjust.getAdidWithTimeout(5000) // Get ADID with a 5-second timeout
  .then((adid) => {
    console.log('Adjust ADID (with timeout):', adid);
  })
  .catch((error) => {
    console.error('Failed to get ADID with timeout:', error);
  });