@appsflyer/plugin-core

Shared JS/TS RPC client core for AppsFlyer SDK 7 plugins (Capacitor, React Native, Cordova).

See AppsFlyerSDK (constructed with an RpcTransport implementation) for the public API, and RpcTransport in src/types.ts for the seam each framework's plugin repo implements.

Every AppsFlyerSDK method takes a single params object typed directly from src/generated/methods.ts (e.g. logEvent(params: LogEventParams)), generated from schema/appsflyer-plugins-rpc-schema.json — the method's wire payload is always exactly that schema's publicApi.parameters shape, with no hand-written reshaping in between.

This package has no native code and no framework dependencies — it does not replace or remove the need for each consuming plugin (Capacitor, Cordova, React Native, NativeScript, Cocos Creator) to have its own iOS (Swift) and Android (Kotlin) native RPC implementation. This package is the shared JS-side contract layer: it resolves a public API call to the correct per-platform wire method/params (resolveRpc(), driven by the schema's rpc.android/rpc.ios/mappings blocks), but every consuming plugin still owns, ships, and maintains its own native code that actually receives that RPC call and talks to the native AppsFlyer SDK. Within this monorepo, nativescript and cocos-creator already depend on it directly ("@appsflyer/plugin-core": "file:../core") and re-export its types/instance. capacitor, cordova, and react-native declare a dependency on @appsflyer/plugin-core too, but on a legacy path (file:../../appsflyer-js-plugin-core) left over from when each was a standalone repo — that path doesn't resolve to this package or exist anywhere in this monorepo, so those three are not actually wired to this package yet. Migrating them onto this package is Phase 2+ of the shared-library migration (see capacitor-appsflyer-plugin-rpc's docs/hld/2026-08-01-shared-js-rpc-plugin-library-hld.md).

Session-ready ordering

init() → registerSessionReadyListener() → start() is a documented convention, not something AppsFlyerSDK mechanically enforces. Calling start() before the session-ready callback has fired will not throw and will not queue the call for later — it sends the start RPC call to native immediately, same as any other method. It is the caller's responsibility to wait for the onReady callback passed to registerSessionReadyListener() before calling start(), per SDK 7's manual startup model.

Implementing a new transport correctly

Follow these steps in order when wiring a new framework (or fixing an existing one) onto this package:

1. Implement RpcTransport (src/types.ts) — the only seam this package requires:
   • call<T>(method, params): forward method and params to your native bridge exactly as given, with no reshaping, unwrapping, or key renaming. Resolve with the native response, or reject with a normalized new AppsFlyerError(code, message).
   • subscribe(listener): wire your native bridge's persistent event channel and invoke listener({ event, data, ... }) for every native event push. Return a ListenerHandle whose remove() tears the subscription down.
2. Construct one AppsFlyerSDK instance: new AppsFlyerSDK(new YourTransport(), { plugin: '<your-framework>', pluginVersion: '<your-package-version>' }). This identity is reported to AppsFlyer's attribution backend via setPluginInfo — it must be your framework's own name/version, never plugin-core's.
3. Call methods using the generated params types only. Every method takes exactly one params object typed by <Method>Params in src/generated/methods.ts (re-exported from the package root). Import the generated type and use it as-is — never hand-write your own options interface, and never guess a shape from an older API version, memory, or another framework's plugin. If the schema changes a method's shape, the generated type changes with it; that's the only place the shape lives.
4. Do not add per-platform special-casing in JS/TS. Dual keys, nested-vs-flat shapes, and key renames between Android/iOS are encoded in schema/appsflyer-plugins-rpc-schema.json's per-method rpc.android/rpc.ios/mappings blocks and must be handled by the native bridge itself. If you're about to write a JS shim that translates one shape into another before calling transport.call(), stop — that logic belongs in native code, or the schema needs updating instead.
5. Respect startup ordering: call init(...), then registerSessionReadyListener(onReady), then call start() only from inside onReady. This is a convention, not something AppsFlyerSDK enforces — start() called early fires immediately rather than throwing or queuing.
6. Push the right event names through subscribe()'s listener, matching each method's publicApi.events in the schema: onSessionReady, onConversionDataSuccess, onConversionDataFail, onDeepLinkReceived. Also forward the legacy onDeepLinking name defensively if your native side ever emits it — not every native bridge normalizes to one name.
7. Verify before calling it done: if you touched the schema, run npm run generate:types; then npm run typecheck and npm test in packages/core. If you're a consuming package, rebuild plugin-core's dist/ (npm run build) and re-typecheck your own package against it — a stale dist/ will hide breakage that looks like a pass.

For AI agents

Rules for any coding agent implementing a new transport, or modifying AppsFlyerSDK after a schema change:

The contract

• RpcTransport.call<T>(method, params) forwards verbatim to the native bridge; RpcTransport.subscribe(listener) wires the persistent event channel and returns a ListenerHandle.
• AppsFlyerSDK is constructed with a transport and a PluginIdentity ({ plugin, pluginVersion }) — this must be the consuming framework's own identity, never js-plugin-core/plugin-core's own package name or version.

Params — read, don't guess

• Every method's argument type is the generated <Method>Params interface in src/generated/methods.ts, exported from the package root. Import and use it directly.
• Never hand-write a params/options interface. Never infer a method's shape from an older version of this SDK, another AppsFlyer plugin's naming convention, or memory of a prior session — read src/generated/methods.ts or schema/appsflyer-plugins-rpc-schema.json directly, every time.
• If the schema changes, the generated type changes with it. Regenerate (npm run generate:types) before writing code against it.

No reshaping in JS

• Per-platform divergence (dual keys, nested vs. flat shapes, renamed fields) lives in the schema's rpc.android/rpc.ios/mappings blocks per method and is the native bridge's responsibility, not this package's or a consuming framework's JS layer.
• Writing a JS/TS shim to translate one param shape into another before calling transport.call() is a signal you're solving the wrong layer — stop and either fix the native bridge or flag that the schema needs updating.

Startup and events

• Ordering: init() → registerSessionReadyListener(onReady) → start() called only inside onReady. This is a convention AppsFlyerSDK does not enforce; calling start() early fires immediately.
• Required event names pushed through subscribe(): onSessionReady, onConversionDataSuccess, onConversionDataFail, onDeepLinkReceived — plus the legacy onDeepLinking name defensively, since not every native bridge normalizes to one name.
• Normalize every native-side error to new AppsFlyerError(code, message) before rejecting a call() promise.

Before declaring anything done

• Schema changed → npm run generate:types.
• Always → npm run typecheck and npm test in packages/core.
• Modified a consuming package (e.g. nativescript, cocos-creator) → rebuild plugin-core's dist/ (npm run build) first, then typecheck the consuming package against it. A stale dist/ will hide real breakage.

Usage example

import { AppsFlyerSDK, RpcTransport, RpcEvent, ListenerHandle } from '@appsflyer/plugin-core';

class ExampleTransport implements RpcTransport {
  async call<T = void>(method: string, params?: Record<string, unknown>): Promise<T> {
    // Forward to your framework's native bridge (Capacitor/RN/Cordova) here.
    return undefined as T;
  }
  subscribe(listener: (event: RpcEvent) => void): ListenerHandle {
    // Wire up your framework's native event channel here.
    return { remove: () => {} };
  }
}

// Each consuming framework supplies its own identity here — this is what
// gets reported to AppsFlyer's attribution backend via setPluginInfo, so it
// must NOT be plugin-core's own name/version.
const sdk = new AppsFlyerSDK(new ExampleTransport(), {
  plugin: 'capacitor',
  pluginVersion: '1.0.0',
});

await sdk.init({ devKey: 'DEV_KEY', appId: 'APP_ID' });
await sdk.registerSessionReadyListener(async () => {
  await sdk.start();
});

Development

• npm run generate:types — regenerate src/generated/methods.ts from schema/appsflyer-plugins-rpc-schema.json
• npm run generate:rpc-map — regenerate src/generated/rpc-map.ts (the per-platform method/param mapping table resolveRpc() reads) from the same schema
• node scripts/generate-sdk-boilerplate.js — after changing the schema, prints a pass-through stub for every method src/appsflyer-sdk.ts doesn't wrap yet; paste each stub in by hand (methods with a non-void result or custom listener/init logic still need manual typing). Not run by build — it only prints, never writes.
• npm test — run the Jest suite (all tests run against an in-memory FakeTransport, no native code)
• npm run typecheck — tsc --noEmit
• npm run build — generate types, generate the RPC map, then compile to dist/

See docs/KNOWLEDGE_BASE.md for a full file-by-file breakdown and flow diagrams.