Initial push of Plunk Next

2025-12-01 09:56:56 +01:00
parent 07cea20262
commit ff1876d580
566 changed files with 89036 additions and 28423 deletions
@@ -0,0 +1,223 @@
+---
+title: Events
+description: Track user actions and behavior
+---
+
+## What are events
+
+Events track user actions in your application. Use them to:
+- Trigger automated workflows
+- Build behavior-based segments
+- Analyze user engagement
+- Track conversion funnels
+
+Common events: signups, purchases, logins, feature usage, page views.
+
+## Tracking events
+
+Use your **public key** for event tracking:
+
+```javascript
+fetch('{{API_URL}}/v1/track', {
+  method: 'POST',
+  headers: {
+    'Authorization': 'Bearer pk_your_public_key',
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    email: '[email protected]',
+    event: 'button_clicked',
+    data: {
+      button: 'signup',
+      page: '/pricing'
+    }
+  })
+});
+```
+
+This creates or updates the contact and tracks the event.
+
+### Persistent vs. Non-Persistent Data
+
+Event data can be either **persistent** (saved to contact) or **non-persistent** (available only to workflows):
+
+**Simple values are persistent** — Saved to contact profile:
+```javascript
+{
+  email: '[email protected]',
+  event: 'subscription_created',
+  data: {
+    plan: 'premium',  // Saved to contact.data.plan
+    mrr: 99.00        // Saved to contact.data.mrr
+  }
+}
+```
+
+**Non-persistent values** — Available only to triggered workflows:
+```javascript
+{
+  email: '[email protected]',
+  event: 'order_placed',
+  data: {
+    totalSpent: 299.99,  // Persistent - saved to contact
+    orderId: {value: 'order-12345', persistent: false},  // Non-persistent - workflows only
+    receiptUrl: {value: 'https://...', persistent: false}  // Non-persistent - workflows only
+  }
+}
+```
+
+**Why use non-persistent data?**
+- Temporary tokens/codes (password reset, verification)
+- One-time URLs or session data
+- Data that shouldn't pollute contact profiles
+- Information needed only for a specific workflow
+
+Non-persistent data is available throughout the entire workflow execution but never stored on the contact record.
+
+## Event structure
+
+Each event stores:
+
+```json
+{
+  "id": "evt_abc123",
+  "name": "purchase",
+  "contactId": "contact_xyz",
+  "data": {
+    "product": "Premium Plan",
+    "amount": 99.00
+  },
+  "createdAt": "2024-03-15T10:30:00Z"
+}
+```
+
+## Using events
+You can use events to trigger workflows, create segments, and analyze user behavior.
+
+## Common event patterns
+
+### Lifecycle events
+
+```javascript
+// User signs up
+track({ email, event: 'signed_up', data: { source: 'homepage' } });
+
+// User activates account
+track({ email, event: 'account_activated' });
+
+// User completes onboarding
+track({ email, event: 'onboarding_completed', data: { steps: 5 } });
+```
+
+### Commerce events
+
+```javascript
+// Add to cart
+track({ email, event: 'cart_added', data: { productId: '123', price: 49 } });
+
+// Purchase
+track({ email, event: 'purchase', data: { orderId: '456', total: 99 } });
+
+// Subscription created
+track({ email, event: 'subscription_created', data: { plan: 'pro', mrr: 29 } });
+```
+
+### Engagement events
+
+```javascript
+// Feature used
+track({ email, event: 'feature_used', data: { feature: 'export' } });
+
+// Page viewed
+track({ email, event: 'page_view', data: { path: '/dashboard' } });
+
+// Login
+track({ email, event: 'logged_in' });
+```
+
+### Automatic events
+
+Plunk sends these automatically:
+
+**Email events:**
+- `email.sent` — Email delivered to inbox
+- `email.opened` — Email opened (first time)
+- `email.clicked` — Link clicked in email
+- `email.bounced` — Email bounced
+- `email.complained` — Spam complaint
+
+**Segment events** (if membership tracking enabled):
+- `segment.entered` — Contact joined segment
+- `segment.exited` — Contact left segment
+
+## Event naming conventions
+
+**Use lowercase with underscores:**
+```
+✓ user_signed_up
+✓ purchase_completed
+✗ UserSignedUp
+✗ purchaseCompleted
+```
+
+**Be specific but concise:**
+```
+✓ trial_started
+✓ subscription_cancelled
+✗ user_started_a_trial
+✗ sub_cancel
+```
+
+**Group related events:**
+```
+user_signed_up
+user_logged_in
+user_deleted_account
+
+subscription_created
+subscription_renewed
+subscription_cancelled
+```
+
+## Managing events
+
+### List events
+
+```bash
+curl -X GET "{{API_URL}}/events?limit=100" \
+  -H "Authorization: Bearer sk_your_secret_key"
+```
+
+### List unique event names
+
+```bash
+curl -X GET {{API_URL}}/events/names \
+  -H "Authorization: Bearer sk_your_secret_key"
+```
+
+Returns all event names tracked in your project.
+
+### Get events for a contact
+
+```bash
+curl -X GET {{API_URL}}/events?contactId=contact_id \
+  -H "Authorization: Bearer sk_your_secret_key"
+```
+
+## Best practices
+
+**Track meaningful actions** — Focus on events that indicate intent or value (signups, purchases, key features).
+
+**Include context** — Add relevant data to understand the event better (product, amount, source).
+
+**Be consistent** — Use the same event names and data structure across your application.
+
+**Don't over-track** — Tracking every click creates noise. Focus on conversion events and key milestones.
+
+**Test your tracking** — Verify events appear in dashboard before building workflows around them.
+
+## What's next
+
+- [Build workflows](/guides/workflows) triggered by events
+- [Create segments](/guides/segments) based on event data
+- [Analyze events](/guides/analytics) to understand user behavior