Developer Docs

Architecture — Four Planes

WAVE is organized into four internal planes. Everything you see in the dashboard belongs to exactly one plane. Understanding the planes makes the product navigation predictable.

Core Concepts

Quick Start

Five steps from zero to your first automated push notification.

1. 1

   Get your API key

   Log in to WAVE → Settings → General → Developer section → copy the API key. Send it as the X-Api-Key header on every request.

2. 2

   Send your first event

   curl -X POST https://wavebitz.com/api/v1/events \
     -H "Content-Type: application/json" \
     -H "X-Api-Key: YOUR_KEY" \
     -d '{
       "customer_id": "usr_001",
       "event_name":  "app_opened",
       "properties":  { "screen": "home" }
     }'

3. 3

   Check the Event Catalog

   WAVE automatically discovers event types. Open Data → Event Catalog — you'll see app_opened appear with its properties. No configuration needed.

4. 4

   Register a push device

   From your mobile app, call POST /api/v1/devices/register with the FCM token. This links the device to the customer so WAVE can deliver push notifications.

5. 5

   Create a Journey

   Go to Automation → Journeys → New Journey. Set the trigger to app_opened, add a push action, and click Publish.

Analytics

Analytics → Analytics

The Analytics page is the health dashboard for your Execution Plane. It shows campaign-level delivery stats and journey execution counts side by side.

Customers

Audience → Customers

WAVE creates a customer record the first time it sees a customer_id. You can enrich that record at any time using the Identify endpoint, which merges attributes into the existing profile.

Customer Profile

The customer profile has three layers:

• Attributes — arbitrary key/value pairs you send (name, tier, city, birth_date)
• Metrics — behavioral measures computed from event history
• Classifications — labels derived from metric thresholds you define

Customer Timeline

The customer detail page shows the complete activity timeline for a customer — four orthogonal layers in reverse chronological order. Use it to debug a journey or verify that events are arriving correctly.

• Event — raw behavioral events from your app (e.g. cart_abandon_detected)
• Journey Enrolled / Rejected — whether the customer entered or was blocked from a journey, with the reason
• Action Executed — Wave fired an automation rule (send email, send push, etc.)
• Delivery — provider-level confirmation; shows Opened and Clicked timestamps inline when available

{
  "name":       "Budi Santoso",
  "tier":       "premium",
  "city":       "Jakarta",
  "birth_date": "1990-04-15",
  "balance":    12500000
}

Events

Data → Events

The Events is the raw, append-only record of every event WAVE has received. Search and filter by customer ID, event name, or time range. Events are immutable — they cannot be edited or deleted after ingestion.

Event Catalog

Data → Event Catalog

The Event Catalog is WAVE's schema layer. It discovers event types automatically as events arrive — you never define schemas upfront. Every unique event name becomes a catalog entry, along with all property keys WAVE has seen for that type.

The Catalog powers Journey Studio — when you pick a trigger event, the condition editor knows which properties are available and their observed types.

Metrics

Intelligence → Metrics

Metrics are behavioral measures computed automatically from a customer's event history. They update on every event — no batch jobs, no manual refresh. Metrics appear on the customer profile and can be used as segment predicates and journey conditions.

Built-in Metrics

Classifications

Intelligence → Classifications

Classifications let you attach a meaningful label to every customer using IF/THEN rules over your Metrics. Each rule is evaluated top-to-bottom — the first match wins, and the result is stored on the customer profile and updated whenever a relevant Metric changes.

Example Classifications

Classifications appear on every customer profile and can be used in Segment rules and journey entry conditions alongside Metrics and attributes.

Segments

Audience → Segments

Segments are reusable audience filters. You define rules using customer attributes, Metrics, and Classifications — and WAVE evaluates membership automatically as new data arrives.

Creating a Segment

1. Go to Audience → Segments → New Segment
2. Name the segment (e.g. High-Value Active Customers)
3. Add conditions: total_spend_30d > 1000000 AND days_since_last_event < 14
4. Save. WAVE immediately evaluates membership across all customers.

Predicate types

• Attribute predicates — filter on customer profile fields (tier, city, birth_date)
• Metric predicates — filter on engagement_score, days_since_last_event, events_last_30d
• Classification predicates — filter on any Classification you've defined
• Event predicates — filter on event history (has / has not performed an event)

Using Segments

• Journey entry filter — only customers in the segment can enter the journey
• Campaign target — broadcast to everyone in the segment at once

Journeys

Automation → Journeys

Journey Studio is the visual builder for customer journeys. Journeys evaluate in real-time — there is no batch delay. Every journey is versioned: publishing creates a new version, never replaces an existing one.

Anatomy of a Journey

Goal States

Campaigns

Automation → Campaigns

Campaigns are one-time broadcasts to a segment. Unlike journeys, they are triggered manually and are not repeated.

Creating a Campaign

1. Go to Automation → Campaigns → New Campaign
2. Name the campaign and choose channel: Push or Email
3. Choose target: All Customers or a specific Segment
4. Compose the message
5. Click Launch — WAVE delivers to all qualifying customers immediately

Automation Rules

Automation → Automation Rules

Automation Rules are the lower-level rule engine that predates Journey Studio. They support more complex trigger types including dormancy windows, inactivity guards, and event sequence detection (did X, never did Y).

All rule executions appear in Automation → Automation Logs and in the Executions page.

Scheduled Events

Automation → Scheduled Events

Scheduled Events are synthetic events emitted by WAVE on a timer — no client code required. They enter the Events and trigger journeys just like any other event.

Executions

Automation → Executions

The Executions page is WAVE's Assurance Plane. For every journey execution, it records:

• Which customer triggered it and which event
• The event properties at the time of evaluation
• Which journey version was active
• Whether the condition passed or failed, and why
• What action was taken and when it was delivered
• Whether the Goal was achieved, pending, or timed out

Sources

Integrations → Sources

A Source is how behavior events enter WAVE. Every event carries a source type that records where it came from. The Sources page shows live event volume and health per source type.

Imports

Integrations → Imports

The Imports page is a unified audit trail for all batch data entering WAVE — both customer profile imports and event CSV imports.

Every import — success or failure — is logged with: Time · Type · Source file · Rows · Success · Failed · Duration.

Download the CSV template from the Imports page to see the expected column format before uploading.

Webhooks

Integrations → Webhooks

The Webhooks page lets you create inbound webhook endpoints. Each endpoint has a unique URL and an HMAC signing secret. External systems POST events to the URL; WAVE verifies the signature before ingesting.

1. Go to Integrations → Webhooks → Add Endpoint
2. Give it a name (e.g. "Core Banking") — this becomes the source_slug
3. Save. Copy the signing secret that appears — it is shown only once.
4. Send events to the URL using HMAC-SHA256 signature verification

POST  /api/v1/webhooks/{tenantSlug}/{sourceSlug}

See the Webhook API section in the Developer Guide for signature generation code in Python, Node.js, and PHP.

Settings

Settings → Settings

Downloads

Everything you need to integrate WAVE into your application.

Authentication

WAVE uses two authentication mechanisms depending on the endpoint group.

Platform API (Backend → WAVE)

All platform endpoints require your tenant API key:

X-Api-Key: wv_xxxxxxxxxxxxxxxxxxxx

Customer API (Mobile App → WAVE)

Customer-facing endpoints accept either:

• A Bearer token issued by POST /api/v1/auth
• An X-Customer-Id header (for trusted server-side calls)

# Bearer token
Authorization: Bearer <token>
X-Api-Key: wv_xxxx

# Direct customer ID (server-side only)
X-Customer-Id: usr_001
X-Api-Key: wv_xxxx

Track Events

POST  /api/v1/events

The primary ingestion endpoint. Call this from your backend whenever a significant business event occurs.

Request Body

Example

curl -X POST https://wavebitz.com/api/v1/events \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: wv_xxxx" \
  -d '{
    "customer_id":      "usr_001",
    "event_name":       "transfer_completed",
    "occurred_at":      "2026-07-04T03:00:00Z",
    "idempotency_key":  "trx-7f3a9c2d",
    "properties": {
      "amount":           2500000,
      "destination_bank": "BCA",
      "currency":         "IDR"
    }
  }'

Response

// Success
{ "success": true, "event_id": "018f3a9c-..." }

// Deduplicated (idempotency_key seen before)
{ "success": true, "deduplicated": true }

Batch Events

POST  /api/v1/events/batch

Send up to 1,000 events in a single HTTP request. The batch is durably accepted before any processing begins — WAVE returns 202 Accepted once the batch is committed to storage, then processes events asynchronously. Useful for high-throughput backends, mobile SDKs that buffer offline events, or historical data migrations via an Import Session.

Request

Optional batch-level header:

Idempotency-Key: <unique-string>   # optional — deduplicates the whole batch on retry

Example

curl -X POST https://wavebitz.com/api/v1/events/batch \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: wv_xxxx" \
  -H "Idempotency-Key: batch-2026-07-04-001" \
  -d '{
    "events": [
      {
        "customer_id":      "usr_001",
        "event_name":       "login",
        "occurred_at":      "2026-07-04T03:00:00Z",
        "idempotency_key":  "login-usr001-0704"
      },
      {
        "customer_id":      "usr_001",
        "event_name":       "transfer_completed",
        "occurred_at":      "2026-07-04T03:02:00Z",
        "idempotency_key":  "trx-7f3a9c2d",
        "properties": {
          "amount":   2500000,
          "currency": "IDR"
        }
      },
      {
        "customer_id": "usr_002",
        "event_name":  "product_viewed",
        "properties":  { "product_id": "P-9901" }
      }
    ]
  }'

Response — 202 Accepted

{
  "batch_id":    "018f3a9c-...",
  "event_count": 3,
  "status":      "accepted"
}

The batch is durably stored at this point. Processing happens asynchronously — use an Import Session to track per-batch progress for large migrations.

Import Sessions

An Import Session groups multiple batches under a single tracked operation with an explicit lifecycle. Required for historical data migrations — live ingestion does not need one.

Create a Session

POST  /api/v1/imports

Policies are immutable — they cannot be changed after the session is created.

// Create a historical import session (journeys suppressed, CI deferred)
curl -X POST https://wavebitz.com/api/v1/imports \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: wv_xxxx" \
  -d '{
    "mode":               "historical",
    "ci_policy":          "defer",
    "label":              "2024 transaction history"
  }'

// Response — 201 Created
{
  "id":                 "018f3a9c-...",
  "mode":               "historical",
  "automation_policy":  "suppress",
  "ci_policy":          "defer",
  "status":             "open",
  "ci_status":          "deferred",
  "ci_reconciled_at":   null,
  "created_at":         "2026-10-19T08:00:00Z"
}

Track Progress

GET   /api/v1/imports/{id}

{
  "id":                 "018f3a9c-...",
  "status":             "open",
  "ci_status":          "deferred",
  "ci_reconciled_at":   null,
  "progress": {
    "batches": { "total": 120, "processed": 118, "failed": 0, "pending": 2 },
    "events":  { "total": 119840, "processed": 117600, "failed": 0, "pending": 2240 }
  }
}

Complete a Session

POST  /api/v1/imports/{id}/complete

Closes the session. After this call, new batches against this import_id are rejected with 422 import_closed. Idempotent — safe to call more than once. Returns the current progress + ci_status: "pending_reconciliation" for deferred sessions.

php artisan wave:reconcile-ci-import {importId}

Full Migration Flow

// 1. Create session
POST /api/v1/imports  →  { "id": "abc-123", ... }

// 2. Stream batches (repeat until all events are submitted)
POST /api/v1/events/batch  { "import_id": "abc-123", "events": [...] }

// 3. Close the session
POST /api/v1/imports/abc-123/complete

// 4. Poll until all batches are processed
GET  /api/v1/imports/abc-123  →  progress.batches.pending == 0

// 5. Reconcile CI (deferred imports only)
php artisan wave:reconcile-ci-import abc-123

// 6. Confirm
GET  /api/v1/imports/abc-123  →  ci_status: "reconciled"

Identify Customers

POST  /api/v1/customers/identify

Creates or updates a customer profile. Safe to call repeatedly — attributes are merged, not replaced.

{
  "customer_id": "usr_001",
  "attributes": {
    "name":       "Budi Santoso",
    "tier":       "premium",
    "city":       "Jakarta",
    "birth_date": "1990-04-15"
  }
}

Batch Identify

POST  /api/v1/customers/identify/batch

Upsert up to 1,000 customer profiles in a single request. Same merge semantics as the single identify call — existing attributes not in the payload are preserved. Useful for bulk imports, nightly sync jobs, or any server-side operation where you need to upsert many customers at once.

{
  "customers": [
    {
      "customer_id": "usr_001",
      "attributes": {
        "name":  "Budi Santoso",
        "email": "budi@example.com",
        "tier":  "premium"
      }
    },
    {
      "customer_id": "usr_002",
      "attributes": {
        "name":  "Siti Rahayu",
        "email": "siti@example.com",
        "tier":  "standard"
      }
    }
  ]
}

// Response
{
  "count": 2,
  "results": [
    { "customer_id": "usr_001", "success": true },
    { "customer_id": "usr_002", "success": true }
  ]
}

Each batch request counts as one request against the identify rate limit (default 60 req/min). Results are returned in the same order as the input array.

Location

Attach a location object to any identify call or to any event's properties — Wave extracts and indexes it automatically, enabling within area and within radius segment predicates. The most recent location seen across all calls wins.

Via identify

{
  "customer_id": "usr_001",
  "attributes": {
    "location": {
      "lat":         -6.2088,
      "lng":         106.8456,
      "city":        "Jakarta",
      "district":    "Gambir",
      "postal_code": "10110",
      "source":      "gps"    // "gps" | "ip" | "manual"
    }
  }
}

Via any event

{
  "customer_id": "usr_001",
  "event_name":  "check_in",
  "properties": {
    "location": {
      "lat":    -6.2088,
      "lng":    106.8456,
      "city":   "Jakarta",
      "source": "gps"
    },
    "venue": "Grand Indonesia"
  }
}

Tips: Omit lat and lng if coordinates are unavailable — do not pass 0, 0 as a placeholder. The text fields (city, district, postal_code) are optional and power the within area predicate independently of coordinates.

Register Devices

POST  /api/v1/devices/register

Links an FCM push token to a customer. Call this on app launch after the user is authenticated, and whenever the FCM token refreshes.

{
  "customer_id": "usr_001",
  "token":       "fcm-token-here",
  "platform":    "android"   // "android" | "ios"
}

Customer API

Endpoints for customer-facing apps. All require X-Api-Key plus a Bearer token or X-Customer-Id.

POST  /api/v1/auth

// Request
{ "customer_id": "usr_001", "pin": "123456" }

// Response
{ "token": "abc123...", "customer": { "id": "usr_001", "name": "Budi", "tier": "premium" } }

GET   /api/v1/me

GET   /api/v1/me/executions

GET   /api/v1/me/notifications

Content Cards

Content Cards are persistent in-app messages that live in a feed inside your app — unlike push notifications, they remain visible until the customer dismisses them. Wave delivers them through journeys and campaigns; your app reads and manages them via these endpoints.

GET   /api/v1/content-cards

// Response
[
  {
    "id":         "cc_01j8p...",
    "title":      "You have Rp 50,000 cashback waiting",
    "body":       "Complete a transfer before Sunday to claim it.",
    "image_url":  null,
    "cta_label":  "Transfer Now",
    "cta_url":    "/transfer",
    "created_at": "2026-07-04T03:00:00Z"
  }
]

POST  /api/v1/content-cards/{id}/impression

POST  /api/v1/content-cards/{id}/click

POST  /api/v1/content-cards/{id}/dismiss

CSV Import

Upload historical or batch data via CSV. Go to Integrations → Imports and use the upload button for events or customer profiles. Download the template from the same page to see the exact column format.

Event CSV — Required Columns

Example

customer_id,event_name,occurred_at,amount,currency
usr_001,transfer_completed,2026-01-15T01:30:00Z,2500000,IDR
usr_002,top_up,2026-01-15T02:00:00Z,500000,IDR

Webhook API

Webhooks let external systems push events to WAVE without using the platform API key. Each webhook endpoint is created under Integrations → Webhooks and has its own signing secret.

Endpoint URL

POST  /api/v1/webhooks/{tenantSlug}/{sourceSlug}

Payload Format

The webhook payload uses a flat JSON structure — no nested properties object. Fields customer_id and event_name are required; all other fields become event properties automatically.

{
  "customer_id":      "usr_001",
  "event_name":       "purchase_completed",
  "occurred_at":      "2026-07-04T09:00:00+07:00",
  "idempotency_key":  "ord-b001-purchase",
  "order_id":         "ORD-B001",
  "amount":           2000000,
  "product_name":     "Flexi Loan"
}

HMAC Signature

Compute HMAC-SHA256 over the raw request body bytes using your endpoint secret. Send it in the X-Wave-Signature header.

// Python
import hmac, hashlib, json

body = json.dumps(payload, separators=(",", ":")).encode()
sig  = "sha256=" + hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
# Header: X-Wave-Signature: {sig}

// PHP
$body = json_encode($payload, JSON_UNESCAPED_UNICODE);
$sig  = 'sha256=' . hash_hmac('sha256', $body, $secret);

// Node.js
const body = JSON.stringify(payload);
const sig  = 'sha256=' + crypto.createHmac('sha256', SECRET).update(body).digest('hex');

Read API

The Read API exposes customer intelligence, segment membership, campaign delivery status, and journey execution history. All endpoints are scoped to the authenticated tenant and require an X-Api-Key header. Rate limit: 120 requests/min per tenant.

Calculated Fields

Returns all tenant-defined Calculated Fields for the customer. Fields that have not been computed yet are included with status: "no_data".

GET  /api/v1/customers/{customerId}/intelligence/fields
GET  /api/v1/customers/{customerId}/intelligence/fields/{slug}

// GET /api/v1/customers/usr_001/intelligence/fields
{
  "customer_id": "usr_001",
  "data": [
    {
      "field":       "loyalty_tier",
      "label":       "Loyalty Tier",
      "value":       "gold",
      "status":      "available",
      "computed_at": "2026-10-20T05:00:00.000000Z"
    },
    {
      "field":       "risk_segment",
      "label":       "Risk Segment",
      "value":       null,
      "status":      "no_data",
      "computed_at": null
    }
  ]
}

CI Metrics

Returns all tenant-defined CI Metrics with computed float values. The -1.0 sentinel (stored when no matching events exist) is normalized to null with status: "no_data" — it never reaches the API response.

GET  /api/v1/customers/{customerId}/intelligence/metrics
GET  /api/v1/customers/{customerId}/intelligence/metrics/{slug}

// GET /api/v1/customers/usr_001/intelligence/metrics
{
  "customer_id": "usr_001",
  "data": [
    {
      "metric":      "total_orders",
      "label":       "Total Orders",
      "value":       42.0,
      "status":      "available",
      "computed_at": "2026-10-20T05:00:00.000000Z"
    },
    {
      "metric":      "days_since_last_purchase",
      "label":       "Days Since Last Purchase",
      "value":       null,
      "status":      "no_data",
      "computed_at": null
    }
  ]
}

Segment Membership

Returns the segments the customer currently belongs to — evaluated live at request time. An empty array means the customer matches no segments (not an error).

GET  /api/v1/customers/{customerId}/segments

// GET /api/v1/customers/usr_001/segments
{
  "customer_id": "usr_001",
  "data": [
    { "id": 4, "slug": "high-value",   "name": "High-Value Customers" },
    { "id": 7, "slug": "reactivation", "name": "Reactivation Candidates" }
  ]
}

Campaign Delivery

Returns the latest delivery attempt per channel for a specific customer + campaign. Only is_latest = true rows are returned — retried deliveries are coalesced. An empty array means the campaign has not been delivered to this customer yet.

GET  /api/v1/customers/{customerId}/campaigns/{campaignId}/delivery

// GET /api/v1/customers/usr_001/campaigns/12/delivery
{
  "customer_id": "usr_001",
  "campaign_id": 12,
  "data": [
    {
      "channel":          "push",
      "status":           "delivered",
      "sent_at":          "2026-10-20T05:00:00.000000Z",
      "delivered_at":     "2026-10-20T05:00:04.000000Z",
      "first_opened_at":  "2026-10-20T05:03:11.000000Z",
      "failure_reason":   null
    },
    {
      "channel":          "email",
      "status":           "failed",
      "sent_at":          "2026-10-20T05:00:00.000000Z",
      "delivered_at":     null,
      "first_opened_at":  null,
      "failure_reason":   "550 Mailbox does not exist"
    }
  ]
}

Journey Executions

Returns the customer's journey execution history, ordered most-recent first. Use ?limit= to control page size (default 50, max 100).

GET  /api/v1/customers/{customerId}/executions[?limit=50]

// GET /api/v1/customers/usr_001/executions?limit=5
{
  "customer_id": "usr_001",
  "data": [
    {
      "id":           1041,
      "journey_id":   3,
      "journey_name": "Reactivation — 30 days",
      "status":       "sent",
      "fire_at":      "2026-10-20T05:00:00.000000Z",
      "sent_at":      "2026-10-20T05:00:01.000000Z",
      "skip_reason":  null
    },
    {
      "id":           987,
      "journey_id":   1,
      "journey_name": "Welcome Series",
      "status":       "skipped",
      "fire_at":      "2026-09-01T08:00:00.000000Z",
      "sent_at":      null,
      "skip_reason":  "goal_already_met"
    }
  ]
}

Journey Deliveries

Returns all delivery records for a journey across every customer who entered it, ordered sent_at DESC. Use this to build custom delivery reports or populate your own analytics. Supports cursor-based pagination via ?cursor=.

GET  /api/v1/journeys/{journeyId}/deliveries[?limit=50&cursor=988]

{
  "journey_id": 3,
  "data": [
    {
      "customer_id":      "usr_001",
      "channel":          "push",
      "status":           "opened",
      "sent_at":          "2026-10-20T05:00:01.000000Z",
      "delivered_at":     "2026-10-20T05:00:03.000000Z",
      "first_opened_at":  "2026-10-20T05:04:12.000000Z",
      "first_clicked_at": null,
      "failure_reason":   null
    }
  ],
  "meta": {
    "limit":       50,
    "has_more":    true,
    "next_cursor": 988
  }
}

Pass next_cursor as ?cursor= on the next request to fetch the following page. has_more: false means you have reached the last page. Limit: 1–200, default 50.

Error responses

Mobile Push Setup

Wave delivers push notifications through your own Firebase project — it never shares a sending identity across tenants. The setup path depends on whether your app already uses Firebase Cloud Messaging.

Path A — No FCM yet

1. Create a Firebase project

1. Go to console.firebase.google.com → Create project
2. In Project Settings → Cloud Messaging confirm Cloud Messaging is enabled
3. Add your platform app (Android / iOS / Web) via Add app and follow the native setup wizard — this gives you google-services.json (Android), GoogleService-Info.plist (iOS), or a firebaseConfig object (Web)

2. Upload your service account to Wave

1. Firebase Console → Project Settings → Service accounts → Generate new private key → download the JSON
2. Wave dashboard → Settings → Channels → Push Notifications → upload that JSON file

3. Add firebase_messaging to your app and wire the token

Add the Firebase Messaging package for your platform, then pass the token to Wave after identify(). Always listen for token rotation — a stale token causes silent delivery failures.

// pubspec.yaml: add firebase_core, firebase_messaging
await Firebase.initializeApp();
Wave.init(baseUrl: 'https://wavebitz.com', apiKey: 'wv_...');

await Wave.instance.identify(user.id);
final token = await FirebaseMessaging.instance.getToken();
if (token != null) await Wave.instance.registerDevice(token);
FirebaseMessaging.instance.onTokenRefresh.listen((t) => Wave.instance.registerDevice(t));

// npm install @react-native-firebase/app @react-native-firebase/messaging
Wave.init({ baseUrl: 'https://wavebitz.com', apiKey: 'wv_...' });

await Wave.instance.identify(user.id);
const token = await messaging().getToken();
await Wave.instance.registerDevice(token);
messaging().onTokenRefresh(t => Wave.instance.registerDevice(t));

Path B — Already using FCM

Your Firebase project and native SDK are already in place. You need to do three things: upload credentials to Wave, register the token, and guard your existing handlers.

1. Upload your service account to Wave

1. Firebase Console → Project Settings → Service accounts → Generate new private key → download the JSON
2. Wave dashboard → Settings → Channels → Push Notifications → upload that JSON file

2. Register the token with Wave

Find where you already call getToken() and onTokenRefresh — add the Wave calls there. No new FCM setup needed.

await Wave.instance.identify(user.id);

// Already have this — add the Wave call
final token = await FirebaseMessaging.instance.getToken();
if (token != null) await Wave.instance.registerDevice(token);  // ← add

// Already have this — add the Wave call
FirebaseMessaging.instance.onTokenRefresh.listen((t) => Wave.instance.registerDevice(t));  // ← add

await Wave.instance.identify(user.id);

const token = await messaging().getToken();   // already have this
await Wave.instance.registerDevice(token);     // ← add

messaging().onTokenRefresh(t => Wave.instance.registerDevice(t));  // ← add

3. Guard your existing handlers

Add one check at the top of each FCM handler. Without it your foreground handler may double-display Wave notifications and your tap handler may misroute them.

FirebaseMessaging.onMessage.listen((message) {
  if (Wave.isWaveNotification(message.data)) return;  // ← add
  showLocalNotification(message);
});

FirebaseMessaging.onMessageOpenedApp.listen((message) {
  final id = Wave.deliveryId(message.data);
  if (id != null) { Wave.instance.trackPushOpened(id); return; }  // ← add
  navigateTo(message.data['screen']);
});

messaging().onMessage(async message => {
  if (Wave.isWaveNotification(message.data)) return;  // ← add
  showLocalNotification(message);
});

messaging().onNotificationOpenedApp(async message => {
  const id = Wave.deliveryId(message.data);
  if (id) { await Wave.instance.trackPushOpened(id); return; }  // ← add
  navigateTo(message.data.screen);
});

Flutter SDK

The WAVE Flutter SDK wraps the REST API for mobile apps — event tracking, customer identification, push device registration, and more. Timestamps are automatically converted to UTC before sending.

Step 1 — Add the package

Extract the zip into your project, then add it as a local path dependency in pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  flutter_wave_sdk:
    path: ./flutter_wave_sdk   # folder extracted from the zip

Then run flutter pub get.

Step 2 — Initialise at app startup

Call Wave.init() once in main.dart before runApp(). Your API key is in the WAVE dashboard under Settings → Developer.

import 'package:flutter_wave_sdk/wave_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  Wave.init(
    baseUrl: 'https://wavebitz.com',
    apiKey:  'wv_your_api_key_here',
  );

  runApp(const MyApp());
}

Step 3 — Identify the customer on login

Call identify() as soon as you know who the user is — typically after a successful login or session restore. This sets the customer ID for all subsequent track() calls.

await Wave.instance.identify(
  'usr_001',                   // your internal user ID
  attributes: {
    'name':  'Budi Santoso',
    'email': 'budi@example.com',
    'tier':  'gold',
  },
);

Step 4 — Register the push token and handle token refresh

After calling identify(), register the current FCM token with Wave. FCM rotates tokens periodically — listen for onTokenRefresh and re-register whenever it changes. Skipping this causes silent delivery failures after token rotation.

// Register current token
final fcmToken = await FirebaseMessaging.instance.getToken();
if (fcmToken != null) {
  await Wave.instance.registerDevice(fcmToken);
}

// Re-register whenever FCM rotates the token
FirebaseMessaging.instance.onTokenRefresh.listen((newToken) {
  Wave.instance.registerDevice(newToken);
});

Logout and account switching

When a customer logs out, call identify() with a new customer ID on the next login — Wave will associate the device token with the new customer. If you want to stop push delivery immediately on logout (e.g. shared devices), deregister the token first:

// On logout — optional, only needed for shared/public devices
await Wave.instance.deregisterDevice();

// On next login — Wave associates the token with the new customer
await Wave.instance.identify(newUser.id, attributes: { ... });
final token = await FirebaseMessaging.instance.getToken();
if (token != null) await Wave.instance.registerDevice(token);

Step 5 — Report push notification opens

Wave embeds a wave_delivery_id in every push notification's data payload. Call trackPushOpened() when the user taps the notification so WAVE can record the engagement on the Delivery ledger.

// In main() — after Firebase.initializeApp()
FirebaseMessaging.onMessageOpenedApp.listen((message) {
  // Handle deep-link navigation
  pushNavSignal.value = screenToTab(message.data['screen']);

  // Report the open to Wave
  final deliveryId = message.data['wave_delivery_id'] as String?;
  if (deliveryId != null) {
    try {
      Wave.instance.trackPushOpened(deliveryId);
    } catch (_) {
      // Wave not yet initialized — user was logged out when notification arrived.
    }
  }
});

Step 6 — Track events

Call track() wherever meaningful actions happen. All extra fields go into properties and are stored on the event record.

// Basic event
await Wave.instance.track('product_viewed');

// Event with properties
await Wave.instance.track(
  'transfer_completed',
  properties: {
    'amount':      2500000,
    'currency':    'IDR',
    'destination': 'BCA-1234567890',
  },
  idempotencyKey: 'TRX-7f3a9c2d',   // prevents duplicate ingestion on retry
  occurredAt:     DateTime.now(),    // converted to UTC automatically
);

Error handling

All SDK methods throw WaveException on failure. Wrap calls in try/catch where delivery is business-critical.

import 'package:flutter_wave_sdk/wave_flutter.dart';

try {
  await Wave.instance.track('checkout_started', properties: {'cart_total': 150000});
} on WaveException catch (e) {
  // e.message  — human-readable error
  // e.statusCode — HTTP status code (401, 422, 429, 5xx)
  debugPrint('Wave error ${e.statusCode}: ${e.message}');
}

Complete integration example

A typical session lifecycle — init once, identify on login, register device and listen for token refresh, track throughout the session, deregister on logout.

// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();   // your existing Firebase init — Wave reuses it

  Wave.init(
    baseUrl: 'https://wavebitz.com',
    apiKey:  'wv_your_api_key_here',
  );

  runApp(const MyApp());
}

// auth_service.dart — after successful login
Future<void> onLoginSuccess(User user) async {
  // 1. Identify the customer
  await Wave.instance.identify(user.id, attributes: {
    'name':  user.name,
    'email': user.email,
    'tier':  user.tier,
  });

  // 2. Register current push token
  final token = await FirebaseMessaging.instance.getToken();
  if (token != null) {
    await Wave.instance.registerDevice(token);
  }

  // 3. Keep Wave in sync when FCM rotates the token
  FirebaseMessaging.instance.onTokenRefresh.listen((newToken) {
    Wave.instance.registerDevice(newToken);
  });

  // 4. Track the login event
  await Wave.instance.track('customer_login');
}

// auth_service.dart — on logout (shared/public devices only)
Future<void> onLogout() async {
  await Wave.instance.deregisterDevice();
}

// transfer_screen.dart — after a successful transfer
Future<void> onTransferComplete(Transfer tx) async {
  await Wave.instance.track(
    'transfer_completed',
    properties: {
      'amount':      tx.amount,
      'currency':    'IDR',
      'destination': tx.destinationAccount,
      'type':        tx.type,
    },
    idempotencyKey: tx.referenceId,
    occurredAt:     tx.completedAt,
  );
}

Coexisting with existing FCM handlers

If your app already handles FCM messages, use wave_delivery_id in the payload to route Wave notifications separately. Without this check, your foreground handler may double-display Wave notifications, and your tap handler may misroute them.

Foreground messages

The OS does not auto-display notifications when the app is in the foreground — your onMessage handler controls display. Skip Wave notifications here; the FCM payload already carries a notification block that the OS will show when the app is backgrounded.

FirebaseMessaging.onMessage.listen((message) {
  if (message.data.containsKey('wave_delivery_id')) {
    return; // Wave handles its own display — skip your custom logic
  }
  // Your existing foreground notification display
  showLocalNotification(message);
});

Notification taps

Route by wave_delivery_id before your deep-link logic so Wave taps are recorded and your navigator isn't given a payload it doesn't recognise.

FirebaseMessaging.onMessageOpenedApp.listen((message) {
  final deliveryId = message.data['wave_delivery_id'] as String?;
  if (deliveryId != null) {
    Wave.instance.trackPushOpened(deliveryId);
    // Handle any Wave-specific deep link here if needed
    return;
  }
  // Your existing deep-link / navigation logic
  navigateTo(message.data['screen']);
});

Background messages

The OS shows Wave notifications automatically in the background — no action needed in your background handler unless you want to track the open. Wave never registers its own onBackgroundMessage, so yours is always the only one.

@pragma('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  if (message.data.containsKey('wave_delivery_id')) {
    return; // OS already showed it; tracking happens on tap via onMessageOpenedApp
  }
  // Your existing background handling
  await handleBackgroundMessage(message);
}

void main() async {
  FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler);
  // ...
}

API reference

React Native SDK

The Wave React Native SDK wraps the REST API for React Native and Expo apps — event tracking, customer identification, push device registration, and notification routing. Pure TypeScript, no native modules.

Step 1 — Add the package

Extract the zip into your project, then add it as a local dependency in package.json:

"dependencies": {
  "wave-react-native": "file:./wave-react-native"
}

Then run npm install (or yarn).

Step 2 — Initialise at app startup

Call Wave.init() once before mounting your root component. Your API key is in the Wave dashboard under Settings → Developer.

import { Wave } from 'wave-react-native';

Wave.init({
  baseUrl: 'https://wavebitz.com',
  apiKey:  'wv_your_api_key_here',
});

Step 3 — Identify the customer

Call after login or session restore. This links all subsequent track() calls to that customer's profile.

await Wave.instance.identify('usr_001', {
  attributes: {
    name:  'Budi Santoso',
    email: 'budi@example.com',
    tier:  'gold',
  },
});

Step 4 — Register device and handle token refresh

Call after identify() whenever the FCM token is available. Listen for rotation to prevent silent delivery failures.

import messaging from '@react-native-firebase/messaging';

// Register current token
const token = await messaging().getToken();
await Wave.instance.registerDevice(token);

// Re-register on rotation
messaging().onTokenRefresh(newToken => {
  Wave.instance.registerDevice(newToken);
});

Step 5 — Track events

await Wave.instance.track('transfer_completed', {
  properties: {
    amount:      2_500_000,
    currency:    'IDR',
    destination: 'BCA-1234567890',
  },
  idempotencyKey: 'TRX-7f3a9c2d',
});

Step 6 — Logout

For shared or public devices, deregister the token on logout to stop push delivery immediately. On the next login, call identify() and registerDevice() again.

// On logout
await Wave.instance.deregisterDevice();

// On next login
await Wave.instance.identify(newUser.id, { attributes: { ... } });
const token = await messaging().getToken();
await Wave.instance.registerDevice(token);

Coexisting with existing FCM handlers

Use Wave.isWaveNotification(message.data) to route Wave notifications separately from your own. Without this guard your foreground handler may double-display Wave notifications and your tap handler may misroute them.

Foreground messages

messaging().onMessage(async message => {
  if (Wave.isWaveNotification(message.data)) {
    return; // Wave handles display — skip your custom logic
  }
  showLocalNotification(message);
});

Notification taps

messaging().onNotificationOpenedApp(async message => {
  const id = Wave.deliveryId(message.data);
  if (id) {
    await Wave.instance.trackPushOpened(id);
    return;
  }
  navigateTo(message.data.screen); // your existing deep-link logic
});

Background messages

messaging().setBackgroundMessageHandler(async message => {
  if (Wave.isWaveNotification(message.data)) return;
  await handleBackgroundMessage(message);
});

API reference

JavaScript SDK

A lightweight browser SDK for web apps — event tracking, customer identification, device registration, and web push. No build step required; drop in a single <script> tag and call the global WAVE object.

Step 1 — Include the script

Add the script tag before your closing </body>. The SDK is served from the WAVE platform directly — no npm package or bundler needed.

<script src="https://wavebitz.com/sdk/wave.js"></script>

Step 2 — Initialise once

Call Wave.init() once as early as possible — before any other SDK calls. Your API key is in the WAVE dashboard under Settings → General (Developer section).

Wave.init({
  apiKey:  'wv_your_api_key_here',
  baseUrl: 'https://wavebitz.com',
});

Step 3 — Identify the customer on login

Call Wave.identify() as soon as you know who the user is — after login or session restore. This links all subsequent track() calls to that customer's profile.

Wave.identify('usr_001', {
  name:  'Budi Santoso',
  email: 'budi@example.com',
  tier:  'gold',
});

Step 4 — Track events

Call Wave.track() on every meaningful action. All extra fields go into properties and are stored on the event record.

// Basic event
Wave.track('page_viewed');

// Event with properties
Wave.track('transfer_completed', {
  amount:      2500000,
  currency:    'IDR',
  destination: 'BCA-1234567890',
});

Step 5 — Enable web push (optional)

Web push requires a Firebase project. Host the service worker template on your own domain, then call Wave.enablePush() after identify(). The SDK handles permission request, token retrieval, and device registration automatically.

// 1. Download firebase-messaging-sw.js from https://wavebitz.com/sdk/firebase-messaging-sw.js,
//    fill in your Firebase config, and host it at https://yourdomain.com/firebase-messaging-sw.js

// 2. Call after identify()
Wave.enablePush({
  firebaseConfig: {
    apiKey:            'AIza...',
    authDomain:        'your-app.firebaseapp.com',
    projectId:         'your-app',
    storageBucket:     'your-app.appspot.com',
    messagingSenderId: '123456789',
    appId:             '1:123...',
  },
  vapidKey: 'BNj...',   // Firebase Console → Project Settings → Cloud Messaging
});

Step 6 — Report push opens (optional)

WAVE embeds a wave_delivery_id in every push notification's data payload. Call Wave.trackPushOpened() when the user clicks the notification so WAVE can record the engagement on the customer timeline.

The template already includes this handler. If you customise it, use event.waitUntil() so the browser keeps the service worker alive until the fetch completes.

// firebase-messaging-sw.js — notificationclick handler
// (already included in the downloaded template)
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  const deliveryId = event.notification.data?.wave_delivery_id;

  event.waitUntil(
    Promise.all([
      // Wave.trackPushOpened() is not available in a service worker — POST directly
      deliveryId
        ? fetch('https://wavebitz.com/api/v1/push/opened', {
            method:  'POST',
            headers: { 'Content-Type': 'application/json', 'X-Api-Key': 'wv_your_key' },
            body:    JSON.stringify({ delivery_id: deliveryId }),
          }).catch(() => {})
        : Promise.resolve(),

      // Focus existing tab or open a new one
      clients.matchAll({ type: 'window', includeUncontrolled: true }).then((list) => {
        const url = event.notification.data?.url || '/';
        if (list.length > 0) return list[0].focus();
        return clients.openWindow(url);
      }),
    ])
  );
});

Complete integration example

<script src="https://wavebitz.com/sdk/wave.js"></script>
<script>
  // 1. Init once
  Wave.init({ apiKey: 'wv_your_api_key_here', baseUrl: 'https://wavebitz.com' });

  // 2. After the user logs in
  function onLogin(user) {
    Wave.identify(user.id, { name: user.name, email: user.email, tier: user.tier });
    Wave.track('customer_login');
  }

  // 3. Track actions throughout the session
  function onTransferComplete(tx) {
    Wave.track('transfer_completed', {
      amount:      tx.amount,
      currency:    'IDR',
      destination: tx.destinationAccount,
    });
  }
</script>

API reference

Idempotency

WAVE prevents duplicate event ingestion using idempotency keys. If you send the same key twice, WAVE processes the first and silently ignores the second — returning { "deduplicated": true }.

When to use it

• Any time you retry a failed HTTP request (network timeout, 5xx response)
• Transfer / payment events — always include a transaction reference as the key
• Any event that should only trigger a journey once per occurrence

Key format

// Transaction ID from your system (best)
"idempotency_key": "TRX-2026-00182736"

// UUID generated client-side before the attempt
"idempotency_key": "7f3a9c2d-4e1b-4a8f-b3c1-2d9e0f1a5b6c"