Amplitude TypeScript SDKs

The SDK can capture events inside cross-origin <iframe> elements and merge them into the parent page's session replay.

Requirements:

• Both the parent page and each iframe page must load the SDK.
• Both must be initialized with crossOriginIframes.enabled: true.
• Third-party iframes (e.g., Stripe, Google Maps) cannot be captured because they do not load your SDK.

How it works:

• The parent SDK uses a CrossOriginIframeCoordinator to watch for iframe additions/removals and sends postMessage signals (start/stop) to children.
• The child SDK detects it is in an iframe (isInIframe() === true) and enters 'child mode', waiting for the parent's signal before recording.
• Child events are relayed via postMessage and merged into the parent's stream.

Privacy Note: Privacy settings (mask levels, block selectors) configured on the parent do not automatically apply to the iframe. You must configure privacy settings independently on the child page.

// Parent page setup
sessionReplay.init(API_KEY, {
  deviceId: DEVICE_ID,
  sessionId: SESSION_ID,
  crossOriginIframes: { enabled: true },
});

// Child iframe page setup (must also load the SDK)
sessionReplay.init(API_KEY, {
  deviceId: DEVICE_ID,
  sessionId: SESSION_ID,
  crossOriginIframes: { enabled: true },
});

The plugin automatically wraps React Native interaction handlers with Amplitude's ampCapture helper at compile time. This allows UI events to be captured without manual code changes in your JSX.

Transformation Logic

The plugin only transforms known interactive JSX elements that have an expression handler (e.g., onPress={func}). It ignores string handlers and elements without handlers.

Supported Categories

Metadata Captured

If the element has accessibilityLabel or testID, these are copied into the ampCapture properties object. The plugin also automatically adds:

• element: The JSX tag name (e.g., Button).
• component: The enclosing React component or function name (e.g., HomeScreen).

Example

Input JSX:

function HomeScreen() {
  return (
    <Button
      accessibilityLabel="Online test label"
      testID="12345"
      title="Online test"
      onPress={func}
    />
  );
}

Transformed Output:

import { ampCapture } from '@amplitude/analytics-react-native';

function HomeScreen() {
  return (
    <Button
      accessibilityLabel="Online test label"
      testID="12345"
      title="Online test"
      onPress={ampCapture(func, {
        action: 'Press',
        accessibilityLabel: 'Online test label',
        testID: '12345',
        element: 'Button',
        component: 'HomeScreen',
      })}
    />
  );
}

If your environment requires custom request logic (e.g., adding a JWT Authorization header for an authenticated proxy), you can provide handleSendEvents and handleFetchConfig callbacks.

Key Behaviors

• URL Resolution: The SDK handles URL resolution (using trackServerUrl and configServerUrl), batching, retries, and compression. Your callback's only job is to execute the request and return a Response.
• Retries: The SDK calls your callback once per logical attempt. Do not implement your own retry logic; the SDK manages retries and backoff around your callback.
• Error Handling: Non-2xx responses or rejected promises from your callback are handled by the SDK's existing retry and logging logic.
• Web Worker Support: If useWebWorker: true is set, the SDK performs compression off the main thread and delegates only the network call back to the main thread to run your callback.
• Page Exit: For authenticated proxies, the SDK routes the final batch through your callback with keepalive: true instead of using navigator.sendBeacon (which cannot carry custom headers).

import * as sessionReplay from '@amplitude/session-replay-browser';
import type { SendEventsRequest, FetchConfigRequest } from '@amplitude/session-replay-browser';

sessionReplay.init(API_KEY, {
  deviceId,
  sessionId,
  trackServerUrl: 'https://my-proxy.example.com/sr-events',
  configServerUrl: 'https://my-proxy.example.com/sr-config',

  handleSendEvents: async ({ url, method, headers, body, keepalive }: SendEventsRequest) => {
    return fetch(url, {
      method,
      headers: { ...headers, Authorization: `Bearer ${getJwt()}` },
      body,
      keepalive,
    });
  },

  handleFetchConfig: async ({ url, method, headers, signal }: FetchConfigRequest) => {
    return fetch(url, {
      method,
      headers: { ...headers, Authorization: `Bearer ${getJwt()}` },
      signal,
    });
  },
});