Skip to main content

Branch Integration for Nodus

1. Introduction to the Branch Integration​

What Is This Integration?​

Branch is a mobile measurement and deep linking platform that unifies user measurement across different devices, platforms, and channels. This integration allows you to extract pre-aggregated analytics data from Branch for use within the Nodus ecosystem.

Prerequisites:​

  • A Branch account with admin access
  • Branch API Key and Secret from your Branch Dashboard Account Settings
  • Appropriate permissions set on your user account (Aggregate Data and Export access)

Connection Overview:​

The integration functions as a source connector, extracting data from Branch's Query API endpoint and bringing it into the Nodus ecosystem for further transformation and analysis.

2. Platform Setup Documentation (Setup Form for Branch)​

Purpose & Scope​

This section covers how to set up the initial connection between Nodus and Branch by providing the necessary authentication credentials.

Field-by-Field Breakdown:​

Integration Name​

  • Field Name & Label: Integration Name
  • Description & Purpose: Unique identifier used to identify this Branch integration within your Nodus account.
  • Validation Rules & Format: Text string, required field.
  • Examples: "Branch Analytics Production", "Branch Mobile Measurement"
  • Troubleshooting Tips: Use a descriptive name that clearly identifies the specific Branch account or app this integration connects to.

API Key​

  • Field Name & Label: API Key
  • Description & Purpose: The Branch Key used for authentication, specific to your Branch application.
  • Validation Rules & Format: Alphanumeric string, required field.
  • Examples: key_live_abcdefghijklmnopqrstuvwxyz
  • Troubleshooting Tips: This can be obtained from your Branch Dashboard under Account Settings.

API Secret​

  • Field Name & Label: API Secret
  • Description & Purpose: The Branch Secret used for authentication, paired with your Branch Key.
  • Validation Rules & Format: Alphanumeric string, required field.
  • Examples: secret_live_abcdefghijklmnopqrstuvwxyz
  • Troubleshooting Tips: This can be obtained from your Branch Dashboard under Account Settings. Keep this value confidential.

Step-by-Step Guide:​

  1. Log in to your Branch Dashboard
  2. Navigate to Account Settings
  3. Copy your Branch Key and Branch Secret
  4. Enter these values along with a meaningful Integration Name in the Nodus setup form
  5. Save the configuration

3. Extraction/Query Configuration (Extraction Form for Branch)​

Purpose & Overview​

This section covers how to configure data extraction from Branch using the Query API. Branch offers various data sources and aggregation methods for analysis.

Template & Field Documentation:​

Data Source Selection​

  • Field Name & Label: Select a data source
  • Description & Purpose: Defines which type of event data to extract from Branch
  • Validation Rules & Format: Dropdown selection, required field
  • Available Options:
    • Impression (eo_impression)
    • Click (eo_click)
    • Branch CTA View (eo_branch_cta_view)
    • SMS Sent (eo_sms_sent)
    • Open (eo_open)
    • Install (eo_install)
    • Reinstall (eo_reinstall)
    • Web Session Start (eo_web_session_start)
    • Pageview (eo_pageview)
    • Commerce Event (eo_commerce_event)
    • Custom Event (eo_custom_event)
    • Content Event (eo_content_event)
    • Dismissal (eo_dismissal)
    • User Lifecycle Event (eo_user_lifecycle_event)
    • Cost (cost)
    • SKAdNetwork Valid Messages (skadnetwork-valid-messages)
    • Various blocked events (e.g., Click Blocked, Install Blocked)

Aggregation Method​

  • Field Name & Label: Select an aggregation
  • Description & Purpose: Defines how to count events in the results
  • Validation Rules & Format: Dropdown selection, required field
  • Available Options:
    • Unique Count (unique_count) - Counts unique users
    • Total Count (total_count) - Counts total events
    • Revenue (revenue) - Sum of revenue
    • Cost (cost) - Sum of costs
    • Cost in Local Currency (cost-in-local-currency) - Sum of costs in local currency

Lookback Range​

  • Field Name & Label: Lookback Range
  • Description & Purpose: Specifies how many days back to extract data from
  • Validation Rules & Format: Dropdown selection, required field
  • Available Options:
    • 3-day Range
    • 7-day Range (recommended)
  • Troubleshooting Tips: Branch API has a limit of querying 7 days at a time; for longer periods, multiple queries need to be made.

Historic Date Selection​

  • Field Name & Label: Historic Date
  • Description & Purpose: For historical data extraction, specifies the date range
  • Validation Rules & Format: Date picker, required field
  • Troubleshooting Tips: Branch retains data for a rolling 2-year window; dates beyond that won't return results.

Workflow & Examples:​

  1. Select the appropriate data source (e.g., eo_install for installation data)
  2. Choose an aggregation method (e.g., total_count for total installs)
  3. Set the lookback period or specific historic date range
  4. Preview the query to confirm configuration
  5. Execute extraction

Example Use Cases:​

  • Daily installs by OS: Select eo_install data source with total_count aggregation
  • Ad campaign performance: Select eo_click data source with unique_count aggregation
  • Revenue tracking: Select eo_commerce_event with revenue aggregation

4. Troubleshooting & FAQs for Branch​

Common Issues & Error Messages​

Authentication Failures​

  • Error: "Invalid Branch Key or Branch Secret"
  • Solution: Verify credentials in Account Settings; ensure you're using the correct key/secret for the environment (live vs. test)

No Data Returned​

  • Common Causes:
    • Date range beyond Branch's 2-year retention window
    • No events for selected data source
    • Incorrect dimension filtering
  • Solution: Verify date ranges; confirm events are being tracked; check filter logic

Contact & Support Information​