Developer

App SDK overview and install

Run Apex flags and tests in hybrid apps built with Ionic, Angular, Capacitor or Cordova. Install the npm package and configure it with a publishable key.

The App SDK runs Apex flags and tests inside hybrid apps built with Ionic, Angular, Capacitor or Cordova. It reads assigned flag values, records exposures, and sends goals and purchases to Apex.

The package is @drip-apex/app-sdk. It has no runtime dependencies and needs no native plugin. It uses only WebView APIs: fetch, timers, Web Crypto, localStorage and visibility events. It does not change the DOM and does not load the storefront SDK.

How it works

The app calls Apex.configure() once at startup.
The SDK gets the assignments for the device, or for the signed-in user after identify().
Your code reads a flag where it selects content or a code path. The read records the exposure.
Your code calls track() for goals and trackPurchase() for orders.
The SDK queues events on the device and sends them in batches to https://events.drip-apex.com.

Flag reads are synchronous. Before the first response, reads return your default value or the cached assignment.

Install the package

npm install @drip-apex/app-sdk

The same package works in Capacitor and Cordova apps. Capacitor plugins such as Preferences and App are optional. You add them only if you want the integrations described in Angular setup and App lifecycle and offline behaviour.

Cordova apps must allow the events host in their content security policy. See Cordova content security policy.

Get your publishable key and shop ID

In Apex, open Settings → Developers.
On Keys and webhooks, select Create key and choose the Publishable type.
Copy the key. It starts with apx_pk_.
On IDs and references, copy the Shop id.

A publishable key is safe to ship in an app binary. It can only read assignments and send events. Never put a secret API key or a shop secret in the app.

Configure the SDK

import { Apex } from '@drip-apex/app-sdk';
 
await Apex.configure({
  publishableKey: 'apx_pk_live_…',
  shopId: 'YOUR_SHOP_ID',
  applicationId: 'com.example.shop',
  appVersion: '1.0.0',
  screen: () => 'home',
  qaMode: false,
});
 
const enabled = Apex.flag('welcome', false);
await Apex.track('signup_completed');
await Apex.trackPurchase('order-42', 42.5, 'EUR');

configure() never rejects. It resolves when the SDK has loaded its stored state and the first assignment request has finished. It waits at most initTimeoutMs (default 3,000 ms) for that request. A late response still updates flag values.

Call configure() once, in app initialization. Angular apps use an app initializer, as shown in Angular setup.

Create a flag for the app

In Apex, create a feature flag and set Delivery to API. The flag key is the key your code reads, for example welcome. API flags can carry typed values: booleans, strings, numbers or JSON objects. See Flags and typed values.

Options

Option	Default	Use
`publishableKey`	Required	The `apx_pk_` key from Settings → Developers.
`shopId`	Required	The shop ID from IDs and references.
`environment`	`production`	Any other value marks all events as QA.
`qaMode`	`false`	Set `true` in test builds. See Test your build.
`applicationId`	`unknown`	Your bundle or package ID. Apex uses it in screen URLs.
`appVersion`	Empty string	Your app version. Apex shows it in the device lookup.
`screen`	Returns `home`	A function that returns the current route, without query or fragment.
`storage`	`localStorage`	An adapter for durable storage, for example Capacitor Preferences.
`initTimeoutMs`	`3000`	How long `configure()` and `identify()` wait for assignments. `0` skips the wait.
`flushIntervalSeconds`	`5`	Time between event sends. Clamped to 0.1 to 86,400.
`batchSize`	`20`	Events per request. Clamped to 1 to 20.
`queueCapacity`	`2000`	Maximum queued events. Clamped to 1 to 2,000.
`queueRetentionHours`	`47`	How long unsent events stay in the queue. Clamped to 0 to 47.
`refreshJitterSeconds`	`[0, 10]`	Random delay before a foreground assignment refresh.
`platform`	Detected	`ios`, `android` or `web`. Set it only to override detection.
`logger`	None	A function that receives diagnostic lines. See Troubleshooting.
`fetch`	WebView `fetch`	A custom fetch function.
`baseUrl`	`https://events.drip-apex.com`	The Apex events host.

Platform detection

The SDK sets the event platform to ios, android or web. It checks Capacitor getPlatform() first, then Cordova device.platform, then the user agent. If none of these match, it uses web. An explicit platform option takes precedence.

Server-side rendering

You can import the SDK in code that also runs on the server. During server-side rendering, configure() logs once, does no storage or network work, and flags return their defaults. Configure again in the browser to start the SDK.