feat: add isDebug option to override __DEV__ detection

CHANGELOG.md

@@ -1,3 +1,7 @@
+## Unreleased
+
+- Add the optional `isDebug` init option to override the default `__DEV__` detection, so release builds used for internal testing (e.g. TestFlight) can be reported as debug
+
 ## 0.6.0
 
 - Add error reporting: new `trackError(error, { fatal })` function posting structured error reports (type, message, stack trace, severity, kind) with capture-time enrichment and retry on network failures

README.md

@@ -99,6 +99,25 @@ A few important notes:
 3. You do not need to await for the `trackEvent` function, it'll run in the background.
 4. Only strings and numbers values are allowed on custom properties
 
+## Debug Mode
+
+Events are flagged as debug based on `__DEV__`, which separates development data from
+production data on your dashboard.
+
+`__DEV__` is false for every release build, including internal ones such as TestFlight or
+an Android internal testing track, so your own pre-release testing counts as production
+data. Pass the `isDebug` option to decide it yourself:
+
+```js
+Aptabase.init("<YOUR_APP_KEY>", {
+  isDebug: __DEV__ || isRunningInternalBuild(),
+});
+```
+
+When omitted, the SDK keeps using `__DEV__`. The flag applies to both events and error
+reports. This mirrors the `isDebug` option in the web SDK and the `trackingMode` option
+in the Swift SDK.
+
 ## Error Reporting
 
 > Error reporting is in beta. Reports appear on the `Errors` page of your Aptabase dashboard.

llms.txt

@@ -104,6 +104,7 @@ Aptabase.init("<APP_KEY>", {
   flushInterval: 30000, // override flush interval in ms (default: 60s prod, 2s dev)
   enableWeb: true, // enable tracking on React Native Web (disabled by default)
   enableCrashReporting: true, // report uncaught errors and crashes automatically (disabled by default)
+  isDebug: true, // override the default __DEV__ debug detection (e.g. to flag TestFlight builds as debug)
 });
 ```
 

src/client.spec.ts

@@ -36,6 +36,30 @@ describe("AptabaseClient", () => {
     expect(body[0].systemProps).toEqual({ ...env, appVersion: "2.0.0" });
   });
 
+  it("should allow override of isDebug", async () => {
+    const client = new AptabaseClient("A-DEV-000", env, {
+      isDebug: true,
+    });
+
+    client.trackEvent("Hello");
+    await client.flush();
+
+    const body = await fetchMock.requests().at(0)?.json();
+    expect(body[0].systemProps).toEqual({ ...env, isDebug: true });
+  });
+
+  it("should keep the environment isDebug when not overridden", async () => {
+    const client = new AptabaseClient("A-DEV-000", env, {
+      appVersion: "2.0.0",
+    });
+
+    client.trackEvent("Hello");
+    await client.flush();
+
+    const body = await fetchMock.requests().at(0)?.json();
+    expect(body[0].systemProps.isDebug).toEqual(env.isDebug);
+  });
+
   it("should send event with correct props", async () => {
     const client = new AptabaseClient("A-DEV-000", env);
 

src/client.ts

@@ -33,6 +33,9 @@ export class AptabaseClient {
     if (options?.appVersion) {
       this._env.appVersion = options.appVersion;
     }
+    if (typeof options?.isDebug === "boolean") {
+      this._env.isDebug = options.isDebug;
+    }
 
     const isWeb = this._env.osName === "web";
     const isWebTrackingEnabled = isWeb && options?.enableWeb === true;

src/types.d.ts

@@ -17,6 +17,11 @@ export type AptabaseOptions = {
 
   // Automatically report uncaught errors and crashes (disabled by default)
   enableCrashReporting?: boolean;
+
+  // Override whether the app is running in debug mode. Defaults to `__DEV__`,
+  // which is false for any release build, including internal ones such as
+  // TestFlight. Set it to true there to keep those events out of production data.
+  isDebug?: boolean;
 };
 
 /**