Branch

Send events and user data to Branch for deep linking and mobile attribution analytics. Zeotap syncs your warehouse data to Branch via their Event API, enabling you to track standard commerce events, content interactions, lifecycle milestones, and custom application events.

Prerequisites

• A Branch account with access to your Account Settings
• Your Branch Key (public app identifier)
• Your Branch Secret (private server-side credential)

Authentication

Branch uses Branch Key + Secret authentication.

1. Log in to your Branch Dashboard
2. Navigate to Account Settings > Profile
3. Copy your Branch Key (starts with key_live_ or key_test_)
4. Copy your Branch Secret (starts with secret_live_ or secret_test_)
5. Enter both values in Zeotap when creating the destination

Important: Your Branch Secret is a private credential. Never expose it in client-side code. Zeotap stores it encrypted in the secret manager.

Configuration

This destination has no additional configuration fields beyond authentication and target settings.

Target Settings

Supported Operations

Sync Modes

Branch events are append-only. Each sync run sends new events to the Branch Event API. Events cannot be updated or deleted after they are sent.

Audience Sync Modes

Branch does not have a list or audience membership API, so audience syncs are not supported.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

At least one user identifier (developer_identity or browser_fingerprint_id) must be mapped so Branch can associate the event with a user.

Default Destination Fields

How It Works

1. Zeotap reads rows from your configured model or audience
2. Each row is transformed into a Branch event payload using your field mappings
3. User-related fields (developer_identity, os, country, etc.) are placed in the user_data object
4. Fields mapped to custom_data, event_data, or content_items are placed in their respective top-level objects
5. Any unmapped fields are automatically added to custom_data
6. Events are sent individually to the Branch Event API (/v2/event/standard or /v2/event/custom based on your target setting)
7. Authentication is included in each request body via branch_key and branch_secret

Standard Event Names

When using Standard Events, the name field must be one of Branch’s predefined event names:

• Commerce: ADD_TO_CART, ADD_TO_WISHLIST, VIEW_CART, INITIATE_PURCHASE, ADD_PAYMENT_INFO, PURCHASE, SPEND_CREDITS
• Content: SEARCH, VIEW_ITEM, VIEW_ITEMS, RATE, SHARE
• Lifecycle: COMPLETE_REGISTRATION, COMPLETE_TUTORIAL, ACHIEVE_LEVEL, UNLOCK_ACHIEVEMENT

Event Data for Commerce Events

For commerce events, map the event_data field as a JSON object with transaction details:

{
  "revenue": 49.99,
  "currency": "USD",
  "transaction_id": "TXN-12345",
  "shipping": 5.99,
  "tax": 3.50,
  "coupon": "SAVE10",
  "description": "Premium subscription purchase"
}

Content Items

For events involving products or content, map the content_items field as a JSON array:

[
  {
    "$content_schema": "COMMERCE_PRODUCT",
    "$og_title": "Blue Widget",
    "$price": 24.99,
    "$quantity": 2,
    "$sku": "WIDGET-BLUE-001"
  }
]

Rate Limits

Branch applies rate limits to the Event API. While exact thresholds are not publicly documented, Zeotap handles rate limiting automatically:

• 429 responses trigger exponential backoff with retry
• Retry-After headers are respected when present
• Up to 3 retries per event with increasing delays

For high-volume syncs, consider scheduling during off-peak hours to minimize rate limit impact.

Best Practices

• Use Standard Events when possible. Branch provides built-in analytics dashboards for standard event types. Custom events require manual reporting setup.
• Always map a user identifier. Either developer_identity or browser_fingerprint_id must be mapped for Branch to associate events with users.
• Include device context. Mapping os, user_agent, and ip improves Branch’s attribution accuracy.
• Use event_data for commerce fields. Revenue, currency, and transaction details should go in event_data, not custom_data.
• Keep custom_data lightweight. Branch stores custom data for export and webhook delivery. Avoid sending large JSON blobs.

Troubleshooting

Events not appearing in Branch

Verify your Branch Key and Secret are correct and belong to the same app. Check that you are using the correct environment (live vs. test keys). Branch test keys send events to the test environment only.

400 Bad Request errors

Ensure the name field is mapped and contains a valid value. For standard events, the name must exactly match one of Branch’s predefined event names (e.g., PURCHASE, not purchase).

Missing user attribution

Branch requires at least one user identifier to attribute events. Ensure developer_identity or browser_fingerprint_id is mapped in your field configuration.

Rate limiting (429 errors)

Zeotap automatically retries rate-limited requests with exponential backoff. If you see persistent 429 errors, reduce your sync frequency or contact Branch support to increase your rate limits.

Events attributed to wrong users

Double-check that your developer_identity mapping points to a stable, unique user identifier. Avoid using transient IDs like session tokens.

Custom data not appearing in exports

Verify your custom_data field is valid JSON. If mapping individual columns (not a JSON blob), they are automatically collected into the custom_data object. Check your Branch data exports or webhooks to confirm delivery.