@layers/amba 1.0.1 → 4.0.2

package/skill-bundle/references/engagement.md

@@ -0,0 +1,400 @@
+# Engagement
+
+Everything that brings a user back to the app: push notifications + campaigns, segments (rule-based user cohorts), content libraries (daily quotes, lessons, tips with scheduled rotation), onboarding flows, deep links, referrals, and tracked links. The SDK side is mostly read-and-call (`Amba.push.register`, `Amba.content.today`, `Amba.onboarding.nextStep`, `Amba.referrals.claimReferral`); the provisioning side — the part you do — lives behind MCP tools.
+
+## MCP tools
+
+### Push
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_push_campaigns_create` | Create a draft push campaign (title + body + optional segment + optional schedule). | `{ project_id, title: "Don't break your streak!", body: "Log your workout to keep the fire alive.", name: "streak_reminder", segment_id: "seg_active" }` |
+| `amba_push_send_test` | Send a one-off push to a single app_user. Use this as your wire-verify after registering a token. | `{ project_id, user_id, title: "Test", body: "Wired up." }` |
+| `amba_push_campaigns_send` / `amba_send_push_campaign` | Send (or schedule) a draft campaign. | `{ project_id, campaign_id }` |
+| `amba_push_list_campaigns` | List campaigns. | `{ project_id }` |
+| `amba_push_get_campaign` | Read one campaign + its delivery stats. | `{ project_id, campaign_id }` |
+| `amba_push_update_campaign` | Edit a draft. | `{ project_id, campaign_id, title, body, scheduled_at }` |
+| `amba_push_delete_campaign` | Remove a draft / cancel a scheduled campaign. | `{ project_id, campaign_id }` |
+
+### Segments
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_segments_create` / `amba_create_segment` | Create a rule-based user segment. | `{ project_id, name: "Power Users", rules: { all: [{ field: "events.workout_completed.count_7d", op: ">=", value: 5 }] } }` |
+| `amba_segments_list` / `amba_list_segments` | List all segments (system + custom). | `{ project_id }` |
+| `amba_segments_get` | Get one segment by id. | `{ project_id, segment_id }` |
+| `amba_segments_evaluate` | Materialize the segment — returns the set of matching user_ids. | `{ project_id, segment_id }` |
+| `amba_segments_patch` | Edit rules / name / description. | `{ project_id, segment_id, rules: {...} }` |
+| `amba_segments_delete` | Drop a segment. | `{ project_id, segment_id }` |
+
+### Content libraries
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_content_libraries_create` / `amba_create_content_library` | Create a library (daily tips, lessons, quotes). | `{ project_id, name: "Daily Tips", description: "Workout motivation served daily" }` |
+| `amba_content_items_add` / `amba_add_content_items` | Bulk-add items to a library. | `{ project_id, library_id, items: [{ body: "Tip 1" }, { body: "Tip 2" }, ...] }` |
+| `amba_content_bulk_import` | Same as `_items_add` but supports CSV/JSON payloads. | `{ project_id, library_id, format: "json", items: [...] }` |
+| `amba_content_list_libraries` | List libraries in this project. | `{ project_id }` |
+| `amba_content_list_items` | List items in one library. | `{ project_id, library_id, limit: 100 }` |
+| `amba_content_update_item` | Edit one item. | `{ project_id, library_id, item_id, body: "…" }` |
+| `amba_content_delete_item` | Drop an item. | `{ project_id, library_id, item_id }` |
+| `amba_content_schedules_create` / `amba_create_content_schedule` | Schedule a library for daily / weekly / random delivery. | `{ project_id, library_id, name: "Daily rotation", schedule_type: "daily_rotation" }` |
+| `amba_content_list_schedules` | List schedules. | `{ project_id, library_id }` |
+| `amba_content_update_schedule` | Edit a schedule's type or config. | `{ project_id, library_id, schedule_id, schedule_type: "weekly" }` |
+| `amba_content_delete_schedule` | Drop a schedule. | `{ project_id, library_id, schedule_id }` |
+
+The worked example (also captured inside the `amba_create_content_schedule` tool description):
+
+```
+1. amba_content_libraries_create({ project_id, name: "Daily Tips" })
+2. amba_content_items_add({ project_id, library_id, items: [{ body: "Tip 1" }, ...] })
+3. amba_content_schedules_create({ project_id, library_id, name: "Daily rotation", schedule_type: "daily_rotation" })
+4. In-app: const today = await Amba.content.today("Daily Tips");
+```
+
+### Onboarding flows
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_onboarding_create` / `amba_create_onboarding_flow` | Create an onboarding flow definition (ordered steps). | `{ project_id, name: "New user", steps: [{ key: "welcome", type: "screen" }, { key: "goal", type: "question", options: ["lose_weight", "build_muscle", "stay_active"] }, { key: "notif_permission", type: "permission_prompt" }] }` |
+| `amba_onboarding_list` | List flows. | `{ project_id }` |
+| `amba_onboarding_get` | Read one flow. | `{ project_id, flow_id }` |
+| `amba_onboarding_update` | Edit steps. | `{ project_id, flow_id, steps: [...] }` |
+| `amba_onboarding_get_stats` / `amba_get_onboarding_stats` | Funnel stats — step-by-step completion + drop-off rates. | `{ project_id, flow_id }` |
+| `amba_onboarding_delete` | Drop a flow. | `{ project_id, flow_id }` |
+
+### Deep links
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_deeplinks_set_config` | Set the project's deep-link config (custom scheme, universal-link domains, fallback URL). | `{ project_id, scheme: "myapp", universal_links: ["myapp.com"], fallback_url: "https://myapp.com/get" }` |
+| `amba_deeplinks_get_config` | Read the config. | `{ project_id }` |
+| `amba_deeplinks_list` | List existing deep-link records. | `{ project_id }` |
+| `amba_deeplinks_delete` | Drop a deep-link record. | `{ project_id, deeplink_id }` |
+
+### Referrals
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_referrals_create` / `amba_create_referral_program` | Create a referral program (per-program rewards on both sides). | `{ project_id, name: "Invite a friend", referrer_reward: { currency: "gems", amount: 100 }, referee_reward: { currency: "gems", amount: 50 } }` |
+| `amba_referrals_list` | List programs. | `{ project_id }` |
+| `amba_referrals_patch` | Edit rewards / program name. | `{ project_id, program_id, referrer_reward: {...} }` |
+| `amba_referrals_get_stats` / `amba_get_referral_stats` | Per-program acquisition stats. | `{ project_id, program_id }` |
+| `amba_referrals_delete` | Drop a program. | `{ project_id, program_id }` |
+
+### Tracked links
+
+| Tool | Purpose | Example args |
+| --- | --- | --- |
+| `amba_tracked_links_create` / `amba_create_tracked_link` | Create a short tracked link that resolves through Amba and records the click. | `{ project_id, name: "Twitter campaign", destination: "https://myapp.com", utm_source: "twitter" }` |
+| `amba_tracked_links_get_stats` / `amba_get_link_stats` | Click / conversion stats for a link. | `{ project_id, link_id }` |
+
+## SDK init per stack
+
+For all stacks: `Amba.configure(...)` must run before any of the calls below — wire it once at app start (see `identity.md`). The snippets below show only the engagement-specific bits.
+
+### Expo
+
+```bash
+npx expo install @layers/amba-expo expo-notifications expo-device
+```
+
+Push registration:
+
+```tsx
+import * as Notifications from 'expo-notifications';
+import * as Device from 'expo-device';
+import { Platform } from 'react-native';
+import { Amba } from '@layers/amba-expo';
+
+async function registerForPush() {
+  if (!Device.isDevice) return; // simulators can't get a real token
+  const { status: existingStatus } = await Notifications.getPermissionsAsync();
+  let finalStatus = existingStatus;
+  if (existingStatus !== 'granted') {
+    const { status } = await Notifications.requestPermissionsAsync();
+    finalStatus = status;
+  }
+  if (finalStatus !== 'granted') return;
+
+  const { data: token } = await Notifications.getDevicePushTokenAsync();
+  await Amba.push.register(token, Platform.OS === 'ios' ? 'apns' : 'fcm');
+}
+```
+
+Content (daily tip):
+
+```tsx
+import { Amba } from '@layers/amba-expo';
+
+const todayTip = await Amba.content.today('Daily Tips');
+// todayTip may be null if the schedule hasn't rotated in an item yet
+console.log(todayTip?.body);
+```
+
+Onboarding:
+
+```tsx
+const status = await Amba.onboarding.getStatus();
+// status.current_step is the next step the user should see
+// status.completed flips true when the flow is done
+await Amba.onboarding.nextStep({ goal: 'lose_weight' });
+await Amba.onboarding.skipStep();   // for optional steps
+await Amba.onboarding.complete();   // explicit terminal call (idempotent)
+```
+
+Referrals:
+
+```tsx
+const { code } = await Amba.referrals.getReferralCode();
+// Show `code` to the user — they share it with a friend
+// On the friend's device, after sign-in:
+const claim = await Amba.referrals.claimReferral(code);
+```
+
+### React Native (bare)
+
+```bash
+npm install @layers/amba-react-native @react-native-async-storage/async-storage
+# Push token: either expo-notifications (works in bare too) or @react-native-firebase/messaging
+npm install @react-native-firebase/app @react-native-firebase/messaging
+```
+
+Push via React Native Firebase:
+
+```tsx
+import messaging from '@react-native-firebase/messaging';
+import { Platform } from 'react-native';
+import { Amba } from '@layers/amba-react-native';
+
+async function registerForPush() {
+  const authStatus = await messaging().requestPermission();
+  const enabled =
+    authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
+    authStatus === messaging.AuthorizationStatus.PROVISIONAL;
+  if (!enabled) return;
+
+  const token = Platform.OS === 'ios'
+    ? await messaging().getAPNSToken()
+    : await messaging().getToken();
+  if (!token) return;
+  await Amba.push.register(token, Platform.OS === 'ios' ? 'apns' : 'fcm');
+}
+```
+
+Subscribing to topics:
+
+```tsx
+await Amba.push.subscribe('marketing');
+await Amba.push.unsubscribe('marketing');
+```
+
+### Web (browser / Next.js)
+
+Web push uses the browser's Push API + a service worker. The SDK handles registration once you have the subscription:
+
+```ts
+import { Amba } from '@layers/amba-web';
+
+async function registerForWebPush() {
+  const reg = await navigator.serviceWorker.register('/sw.js');
+  const sub = await reg.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
+  });
+  await Amba.push.register(JSON.stringify(sub), 'web');
+}
+```
+
+Content:
+
+```ts
+const tip = await Amba.content.today('Daily Tips');
+if (tip) {
+  document.querySelector('#daily-tip')!.textContent = tip.body;
+}
+```
+
+Onboarding (typical use in a `useEffect`):
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Amba } from '@layers/amba-web';
+
+function OnboardingGate() {
+  const [needsOnboarding, setNeedsOnboarding] = useState(false);
+  useEffect(() => {
+    (async () => {
+      const status = await Amba.onboarding.getStatus();
+      setNeedsOnboarding(!status.completed);
+    })();
+  }, []);
+  return needsOnboarding ? <OnboardingFlow /> : <MainApp />;
+}
+```
+
+### iOS (Swift)
+
+```swift
+import UIKit
+import Amba
+
+class AppDelegate: NSObject, UIApplicationDelegate {
+    func application(_ application: UIApplication,
+                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]?) -> Bool {
+        UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, _ in
+            if granted {
+                DispatchQueue.main.async { application.registerForRemoteNotifications() }
+            }
+        }
+        return true
+    }
+
+    func application(_ application: UIApplication,
+                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+        let token = deviceToken.map { String(format: "%02x", $0) }.joined()
+        Task {
+            try await Amba.push.register(token: token, platform: .apns)
+        }
+    }
+}
+```
+
+Content + onboarding:
+
+```swift
+let today = try await Amba.content.today(channel: "Daily Tips")
+let status = try await Amba.onboarding.getStatus()
+try await Amba.onboarding.nextStep(payload: ["goal": "lose_weight"])
+```
+
+> Don't forget: enable the **Push Notifications** capability in **Xcode → Signing & Capabilities**, and upload an APNs key in app.amba.dev under your project's integrations tab.
+
+### Android (Kotlin)
+
+In your `Application.onCreate`:
+
+```kotlin
+import com.google.firebase.messaging.FirebaseMessaging
+import com.layers.amba.Amba
+import com.layers.amba.push.PushPlatform
+
+FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
+    GlobalScope.launch {
+        Amba.push.register(token = token, platform = PushPlatform.FCM)
+    }
+}
+```
+
+In your `FirebaseMessagingService` subclass:
+
+```kotlin
+override fun onNewToken(token: String) {
+    GlobalScope.launch {
+        Amba.push.register(token = token, platform = PushPlatform.FCM)
+    }
+}
+```
+
+Content + onboarding:
+
+```kotlin
+val today = Amba.content.today("Daily Tips")
+val status = Amba.onboarding.getStatus()
+Amba.onboarding.nextStep(mapOf("goal" to "lose_weight"))
+```
+
+### Flutter
+
+```yaml
+dependencies:
+  amba: ^1.0.0
+  firebase_messaging: ^14.7.0
+```
+
+```dart
+import 'package:amba/amba.dart';
+import 'package:firebase_messaging/firebase_messaging.dart';
+import 'package:flutter/foundation.dart';
+
+Future<void> registerForPush() async {
+  final messaging = FirebaseMessaging.instance;
+  final settings = await messaging.requestPermission();
+  if (settings.authorizationStatus != AuthorizationStatus.authorized) return;
+  final token = defaultTargetPlatform == TargetPlatform.iOS
+      ? await messaging.getAPNSToken()
+      : await messaging.getToken();
+  if (token == null) return;
+  await Amba.push.register(
+    token: token,
+    platform: defaultTargetPlatform == TargetPlatform.iOS
+        ? PushPlatform.apns
+        : PushPlatform.fcm,
+  );
+}
+
+final tip = await Amba.content.today('Daily Tips');
+final status = await Amba.onboarding.getStatus();
+await Amba.onboarding.nextStep({'goal': 'lose_weight'});
+```
+
+## Common follow-ups
+
+Batch these into one or two multi-choice rounds.
+
+1. **Push: who do you target by default?**
+   - All users (no segment)
+   - A custom segment — I'll define one
+   - Don't enable push yet (just register tokens)
+
+2. **Content libraries: do you want to seed a "Daily Tips" library?**
+   - Yes — create a "Daily Tips" library with 7 starter items and a daily-rotation schedule
+   - Yes but seed it empty — I'll add items myself
+   - No
+
+3. **Onboarding: want a default 3-step flow?** (Welcome → primary goal → permission prompt)
+   - Yes
+   - No — I'll build my own flow
+   - Yes but ask me what the goal-question options should be
+
+4. **Referrals: enable a referral program?**
+   - Yes — both sides get 100 of `<currency>` (depends on economy surface; ask if currency isn't wired)
+   - Yes — I'll set the reward myself
+   - No
+
+5. **Deep links: which scheme + domain?**
+   - Custom scheme only (e.g. `myapp://`) — recommended for quick start
+   - Custom scheme + universal links (need to upload the AASA file and Digital Asset Links — I'll set up the records, you serve the files)
+   - Skip — I have my own deep linking
+
+## Re-run behavior
+
+1. Read `.amba/wired.json` for the existing `engagement` block:
+
+   ```json
+   {
+     "surfaces": {
+       "engagement": {
+         "push": { "campaigns": ["streak_reminder"], "registered_token_via": "expo-notifications" },
+         "segments": ["seg_active", "seg_trial"],
+         "content": { "libraries": ["Daily Tips"], "schedules": ["Daily rotation"] },
+         "onboarding": ["new_user"],
+         "referrals": ["invite_a_friend"],
+         "deeplinks": { "scheme": "myapp", "universal_links": ["myapp.com"] }
+       }
+     }
+   }
+   ```
+
+2. Before creating any resource, call the corresponding `_list` tool first:
+   - `amba_push_list_campaigns` — don't recreate a campaign with a key that already exists; offer to edit (`amba_push_update_campaign`) instead.
+   - `amba_segments_list` — segments are keyed by `name`; collide → ask "extend or skip".
+   - `amba_content_list_libraries` — same.
+   - `amba_onboarding_list` — same.
+   - `amba_referrals_list` — same.
+
+3. For push, never auto-send a campaign on re-run. Always create as `draft` and let the user trigger `amba_push_campaigns_send` manually (the tool's own description marks send as the action gate).
+
+4. If the user re-runs and the entry file already has `Amba.push.register(...)`, don't duplicate it. Detection: search for `Amba.push.register` in the entry file.
+
+5. Update `wired.json` to append (not replace) new campaigns, segments, libraries, etc.