Datadog

Prerequisites

• Datadog Account: Sign up here if you don't have one.
• Auth Token: Generate a token from your Datadog dashboard. This must be defined as the environment variable DATADOG_API_KEY.
• Datadog site: specify the site for the API key with DATADOG_SITE (e.g., DATADOG_SITE=datadoghq.eu).
• Complete the Datadog React Native SDK setup and verify a test error reaches Datadog.
• Install the plugin:

npm install @hot-updater/datadog-plugin @datadog/datadog-ci --save-dev

Configure the OTA identity

Each OTA bundle needs its own sourcemap identity. Without a Debug ID, Datadog matches on service, version, bundle name, and platform, then picks the highest build number. Changing buildNumber alone cannot distinguish devices running different OTA bundles for the same native version. See Datadog's matching rules.

The following recipe uses Datadog's versionSuffix option. It assumes the target native app version is 1.0.0. Create a shared module imported by both the app and hot-updater.config.ts:

// Change this suffix for every OTA build, including rebuilds of the same commit.
export const datadogVersionSuffix = "ota.20260930.1";
export const datadogReleaseVersion = `1.0.0-${datadogVersionSuffix}`;

Set the suffix on your existing Datadog SDK configuration before initializing it. This is an excerpt from that initialization module:

import { datadogVersionSuffix } from "./datadog-release";

// config is your existing Datadog SDK configuration.
config.versionSuffix = datadogVersionSuffix;

Datadog adds the dash, so the runtime reports 1.0.0-ota.20260930.1. Keep your existing SDK service name and use that same service in the upload options below. Bundle this shared module into the OTA update; an environment variable set only for the deploy process does not configure the running app. If you also build a native binary from this source, set DATADOG_RELEASE_VERSION to the same full version for Datadog's native-build sourcemap upload.

Use a new suffix for every OTA build and retain that build's value when rolling back or promoting the same files. This recipe targets native version 1.0.0; if the same OTA can run on other native versions, upload the same map under each resulting version or configure Datadog Metro Debug IDs for your build pipeline. withDatadog uploads files; it does not inject Debug IDs or set the runtime SDK version.

Step 1: Wrap your build adapter

Use withDatadog() to wrap any compatible build adapter such as bare.

import { existsSync } from "node:fs";
import { bare } from "@hot-updater/bare";
import { withDatadog } from "@hot-updater/datadog-plugin"; 
import { defineConfig } from "hot-updater";
import { datadogReleaseVersion } from "./datadog-release";

if (existsSync(".env.hotupdater")) {
  process.loadEnvFile(".env.hotupdater");
}

export default defineConfig({
  build: withDatadog( 
    bare({
      enableHermes: false, // or true, depending if you want to use it
      // Required for sourcemap upload
      sourcemap: true, 
    }),
    { 
      // Sort sourcemaps for the same version by this build number.
      buildNumber: "build number", 
      // Match this OTA bundle's runtime SDK version.
      releaseVersion: datadogReleaseVersion, 
      // Datadog service associated with these sourcemaps.
      service: "service", 
    }, 
  ), 
  // .. your other config
});

With a managed provider, hot-updater init keeps this wrapped build when it updates the storage, database, and plugins in hot-updater.config.ts.

Step 2: Deploy

Set a new suffix in datadog-release.ts, then deploy the update to build the bundle and upload its sourcemap with that version.

npx hot-updater deploy -i

Verify symbolication

Keep two devices on different OTA bundles for the same native app version. Use distinct suffixes and make the test error occur at different source lines in each bundle. After both maps have been uploaded, trigger the error on both devices and confirm each stack points to its own original source line.

Check the reported service and version against each upload. A successful upload or a correct stack from only the newest bundle does not verify that older installed bundles still resolve to the right map.