If you use Segment to track certain events, you can add impact.com as a Destination function so that your impact.com program receives events from Segment. The integration supports both web and mobile (iOS & Android) events.

How it works

• In the impact.com platform, you can set up an OAuth connection between your Segment account and your impact.com brand account that supports multiple sources.
• From the Segment spec, four API calls are supported: Track, Page, Screen, and Identify. Event names within each of these APIs can be mapped to either Page Load, Install, or Action event names in impact.com.
• Once configured, impact.com will start receiving event data from Segment through the destination based on your specific configuration.

Implementation overview

Connect impact.com to Segment

The steps below will connect your impact.com brand account to your Segment account and enable your first Segment source.

If you want to add another Segment source to your impact.com brand account, repeat the above steps for any remaining sources — in Step 5, choose the other source you want to connect.

Destination/Connection Settings reference

The table below organizes and describes each of the available settings and configuration options for the impact.com destination function. Items with a red asterisk (*) are required.

Segment Spec: Track calls

The Segment track API call can send event data to impact.com via the Conversions endpoint or the PageLoad endpoint, depending on your configuration.

• track events sent to the Conversions endpoint will be reported as conversions to impact.com, which are attributed to a partner and appear as an action in the impact.com platform (Action Event Names in the Destination/Connection settings).
• track events sent to the PageLoad endpoint may be reported as a Click if they fit that definition (e.g., a track call sent to PageLoad that counts as a Click is an Application Opened event — a visitor opened your mobile app). These can be customized to fit your specific needs.

An example track call would look like:

analytics.track('Order Completed', {
  checkout_id: 'fksdjfsdjfisjf9sdfjsd9f',
  order_id: '50314b8e9bcf000000000000',
  affiliation: 'Google Store',
  total: 27.50,
  subtotal: 22.50,
  revenue: 25.00,
  shipping: 3,
  tax: 2,
  discount: 2.5,
  coupon: 'hasbros',
  currency: 'USD',
  products: [
    {
      product_id: '507f1f77bcf86cd799439011',
      sku: '45790-32',
      name: 'Monopoly: 3rd Edition',
      price: 19,
      quantity: 1,
      category: 'Games',
      url: 'https://www.example.com/product/path',
      image_url: 'https:///www.example.com/product/path.jpg'
    },
    {
      product_id: '505bd76785ebb509fc183733',
      sku: '46493-32',
      name: 'Uno Card Game',
      price: 3,
      quantity: 2,
      category: 'Games'
    }
  ]
});

impact.com passes a unique irclickid query string parameter into the landing page URL when redirecting the user through our tracking domains. The value associated with this parameter is used to perform attribution analysis.

If you're using a Segment JavaScript source on every page of your site, this value is automatically received from Segment (e.g. as part of context.page.url). This works similarly for in-app events, where the Segment Mobile (iOS or Android) source captures an Application Opened event, which is reported to impact.com alongside the anonymousId generated by Segment.

If you’re not using the Segment JavaScript source on every page or the anonymousId is not consistently populated on Track and Page events, we recommend you cache this value in the user’s browser or app (using a cookie or app storage) to pass along with track events — see the Advanced options section.

Track events mapping

impact.com can track multiple events from Segment, but they need to be mapped to corresponding Event Types in your impact.com account. These can be configured as Event Codes for your event types.

Before beginning, go to the Sources screen in your Segment account and take note of your Events names with the Track type:

Track events parameter mapping reference

^[1] — See the Using Click ID section in Advanced options. Note, Click ID is only mapped when the referrer.type is set to impactRadius.
^[2] — Email address will be SHA1 hashed (with a HEX output type) prior to being sent to impact.com. The email input is expected to be plain text (e.g. [email protected]).

^[3] — Customerid value in the page load needs to be 7 or more characters, with 3 being distinct, and without whitespace.
^[4] — this field will only be passed if the products array is not defined. The impact.com Destination expects that revenue will exclude discount. If necessary, this mapping can be overridden through the Custom Parameter Mapping option in the Destination Settings.

Segment Spec: Page calls

The Segment page API call is used to record when a visitor sees a page of your website, along with additional properties about the page.

⚠️

Note

Note: If you’re tracking web events, page calls are required calls that should be enabled in the Destination/Connection settings of impact.com within Segment.

An example call to Segment would look like:

analytics.page("Home")

Page calls are sent to impact.com via the PageLoad endpoint of the impact.com Brand API. They may appear as Clicks if they fit the definition of a unique click, which you can customize.

⚠️

Note

For impact.com to correctly track and attribute actions, it is important to receive the page analytics call on every page load within the website (e.g. not just the home page visit).

Enable Page Events

⚠️

Note

For impact.com to correctly track and attribute actions, it is important to receive the Page analytics call on every page load within the website (e.g. not just the home page visit).

Page Events parameter mapping reference

^[1] – Customerid value in the page load needs to be 7 or more characters, with 3 distinct and without whitespace.

Segment Spec: Screen calls

The Segment screen API call is used to record when a visitor sees a screen of a mobile app — essentially the mobile equivalent of the page call.

💡

Tip

screen calls are optional calls that you can enable in the Destination/Connection settings of impact.com within Segment.

An example call would look like:

[[SEGAnalytics sharedAnalytics] screen:@"Home"];

Screen calls are sent to impact.com via the PageLoad endpoint of the impact.com Brand API. They may appear as Clicks if they fit the definition of a unique click, which you can customize.

Parameter mapping for Screen in impact.com is the same as Page.

Enable Screen events

Segment Spec: Identify calls

The Segment Identify API call is used to associate a user with their actions and record traits about that user.

💡

Tip

Identify calls are optional calls that you can enable in the Destination/Connection settings of impact.com within Segment.

An example call looks like:

analytics.identify('userId123', {
  email: '[email protected]'
});

Identify calls are sent to impact.com via the PageLoad endpoint of the impact.com Brand API, enabling impact.com to update the user identifiers for more accurate correlation.

Enable Identify Calls

Advanced options

Custom parameter mapping

Custom Parameter Mapping enables customized mapping for a parameter. If a default parameter mapping is inconsistent with your schema (or you’ve been advised to create custom mappings), this setting enables you to specify the new parameter names.

Configure a Custom Parameter Mapping

Custom mapping for products

Use this setting instead of Custom Parameter Mapping when overriding the default mapping in the products array. Only mapping of parameters from the products array in Segment are supported.

For example, you can map ItemPrice to product_revenue as below — see the code example below that illustrates the products array and the product_revenue parameter as passed in the array:

{
    "event": "Order Completed",
    "messageId": "123",
    "originalTimestamp": "2021-02-21T11:10:56-04:00",
    "properties": {
      "products": [
        {
          "name": "My Product Name 1",
          "product_revenue": 20,
          "quantity": 1,
          "sku": "my-product-1"
        },
        {
          "name": "My Product Name 2",
          "product_revenue": 20,
          "quantity": 2,
          "sku": "my-product-1"
        }
      ],
      "revenue": 60,
      "shipping": 10,
      "subtotal": 70,
      "tax": 0
    },
    "receivedAt": "2021-02-21T15:10:57.013Z",
    "sentAt": "2021-02-21T15:10:56.000Z",
    "timestamp": "2021-02-21T15:10:57.013Z",
    "type": "track",
    "userId": "abc-12345-6789"
  }

Configure a Custom Mapping for Products

Attributing Track events

If you’re not using the Segment JavaScript source on every page or the anonymousId is not consistently populated on Track and Page events, we recommend you cache this value in the user’s browser or app (using a cookie or app storage) to pass along with track events.

Using Click ID

You can find the value in the query string of the URL. The default parameter is irclickid=, but be sure to verify in the Gateway Tracking Settings of your impact.com brand account. Set context.referrer.id to clickid, and set context.referrer.type to impactRadius. See the context.referrer object example below:

analytics.track('Some Conversion Event' { someProperty: true }, {
  context: {
    referrer: {
      type: 'impactRadius',
      id: <CACHED_CLICK_ID>
    }
  }
})

⚠️

Note

Application Installed events supports real-time correlation between the app store click and install, meaning you wouldn’t need to pass a clickId on an Application Installed event or any other install event name as specified in Install Event Names within your Destination/Connection settings.

Other methods

impact.com uses anonymousId to associate events with the same user’s journey and attribute track events to the original referring event. However, it is common that an advertiser will track initial events like a Sign-up using a Segment Mobile (iOS or Android) or JavaScript source and subsequent events like a Conversion using a server-side source. Whereas anonymousId is provided in the former, it’s usually not present in any of the requests from server-side sources.

The first example below illustrates the problem where we don’t have a common identifier to associate the Page event to the subsequent Sign-Up event. The following options provide 3 different solutions that would allow advertisers to ensure accurate correlation of the page event, containing the referrer information, and subsequent track events.

Use Repeater Destinations to Split Traffic from a Single Source to Multiple Destinations

This approach involves replicating a source using the Segment Repeater destination so that different sources can be configured with different impact.com destinations that have different settings (i.e., different campaigns or parameter mapping).