Hightouch - Server-to-Server Integration for Event Processing

Follow
Avatar
Jared Ornstead
Updated

Hightouch is a data integration platform that enables businesses to sync data between their data warehouses and various other tools or platforms they use for analytics, marketing, and operations. It allows users to easily connect their data warehouse to tools such as CRMs, marketing automation platforms, customer support systems, and more, without the need for complex ETL (Extract, Transform, Load) processes or custom coding.

The Hightouch integration with Singular sends Mobile (iOS/Android) event data from your Hightouch Source(warehouse) using the Singular Server-to-Server(S2S) REST API. This is referred to as a "Destination" in the Hightouch platform. The instructions below illustrate how to configure the Singular Destination in Hightouch.

Requirements Guide for Engineering Teams
  1. A Singular iOS/Android SDK integration in your Mobile app.

    This should include at minimum one in-app event to record a user sign-in event.

    See the Singular Help Center SDK section for documentation on all SDK integration options HERE.

  2. One of the following data capture methods:
  • Recommended: Singular Internal BI configuration

    Configure an event postback to your Internal BI endpoint every time a user sign-in occurs in the Mobile App and save this data to your user table. Read More HERE

  • Or, use In-App code snippets to capture required data points for the Singular Event API

    The Singular data points must be passed back to your warehouse for association with the device/user and available to a Source in Hightouch when syncing events. Singular documents the code snippets required for the key parameters HERE.

To use this integration, you must be using a Hightouch Source with all required Singular data points that match the last known event from the Singular Mobile SDK.

This integration is NOT compatible with Non-Mobile event data. Server or Web Events are not supported.

What's Supported
  1. Hightouch Supported Syncing Type: Events

    Hightouch supports syncing in-app events to Singular

    SUPPORTED SYNC MODES: Insert Only

What's NOT Supported
  1. Session Events
  2. Web Events
  3. Server-Side Events without Mobile data points

The Hightouch integration is not a replacement for the Singular SDK. You must use the Singular SDK in parallel with Hightouch. This is a Hybrid Integration where data collection occurs from both within the client via a Singular issued SDK and via the REST API endpoint for the same device/user. Any event sent from Hightouch to Singular will be associated with the last known Mobile device for the user and cohorted to the last known campaign data for said device.

Getting Started

Start by creating an instance of a Singular destination in Hightouch. Upon creating your instance, you must enter the Singular SDK Key for authentication.

  1. From the Hightouch navigation menu, click on: "Setup > Destinations".
  2. Click the "Add Destination" button.
  3. Search for "Singular" and click Continue.
  4. Enter the Singular SDK Key in the "API Key" field. And click continue.

    Get your Singular "SDK KEY", found in the Singular Dashboard under "Developer Tools > SDK Integration > SDK Keys"


  5. Name the destination, and click "Finish"

Important: If you click the "Test Connection" button, you might see the following error:

This is only because the API requires additional data points which will be configured in the following steps.

Additional Setup

Configure a Model

  1. From the Hightouch Navigation menu select "Models" and Add a New Model.
  2. Select the data Source and click "Continue".
  3. Provide a Name for the Model, and select a Primary Key from the dropdown.

    To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

Configure a Sync

  1. From the Hightouch Navigation menu select "Sync" and "Add Sync".
  2. Select the Model Configured for Singular.
  3. Select the Singular Destination.
  4. Required: Select the Event Name Column from the dropdown menu, to be used as the Singular Event Name.
  5. Required: Select the Timestamp Column from the dropdown menu, to be used as the Singular Event time.
  6. Select the other columns you would like to sync to Singular.

    Configure how to map columns in your query results to fields in your destination. Note that the Singular destination has some conditionally required fields based on the "platform" field.

    Required additional parameter mapping:

    See the Required Event Parameters in the Singular S2S Reference HERE for details on what parameters should be mapped for an event.

    If you don't map the IP field, it will be defaulted with one from Hightouch's servers.

    About Device Identifiers

    For proper attribution of an Event sent from Hightouch to an existing device in Singular, a matching device identifier must be used. If the Internal BI endpoint option was configured to capture data from a sign-in event to the warehouse, then the same identifier should be used on this Event request.

    For iOS - this would be either the IDFA or IDFV. Do not provide "NULL" values or zero'ed identifiers. If the IDFA was not available on the device when the Singular SDK initialized then Singular will be using the IDFV value.

    For Android - this would be either the AIFA(aka. GAID) or ASID. Do not provide "NULL" values or zero'ed identifiers. If the AIFA was not available on the device when the Singular SDK initialized then Singular will be using the ASID value. If neither the AIFA nor ASID values are available on the device, only then should you provide the Android ID (ANDI).

  7. Once the parameters are mapped, you can test the event using the "Test" button.

    Capture the Identifier from the Source data being used in your test, and use the Singular Testing Console to see the event being received in real-time. Learn More on how to test events HERE.

    Example:

    The Mapping


    The Test


    The Singular Testing Console
  8. Once testing is successful, click continue and set your Schedule Type, and click "Finish".

SkAdNetwork Support

To use events sent from Hightouch in Singular's SkAdNetwork(SKAN) conversion models, you must have the "Hybrid SKAN" feature enabled for your Singular Account. Please contact your CSM or submit a Singular Support request for activation.

Events

Any records added to your source are treated as new events and are sent to Singular when your sync runs.

You can use custom mappings to attach custom data relevant to your application.

Custom mappings are included as the "e" parameter of the API request payload.

Tips and troubleshooting

Discrepancies

Discrepancies will occur if device identifiers used on Server-to-Server event requests do not have a matching device identifier in Singular. Be aware of the following possibilities:

  • If an event request is received "before" the Singular SDK has recorded the device identifier, from an App Session, then the event request will be considered the "first session" for the unknown device and Singular will attribute the device as an organic attribution.
  • If the Singular SDK did record a device identifier, but the Singular SDK identifier differs from the device identifier specified in the Server-to-Server Event request then the event will be attributed incorrectly.

Common errors

If you receive errors, ensure that you're including all of Singular's required fields: "Platform", "Package Name", "OS Version" and device identifiers for the relevant Platform.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.