Attribution Integrations: Client-Side and Server-Side (S2S) Clicks (Guide for Singular Partners)

Follow
Avatar
Liz Lauer-Lopez
Updated

Learn about the two types of ways media partners can send clicks to Singular to use for attribution. Make sure to read these first: Integrating with Singular: A Guide for Partners and Integrating with Singular Attribution FAQ (Partners).

 

Client-Side Attribution

A client-side click integration is the most common (and recommended) way to integrate with Singular's attribution service. It lets the advertiser make full use of Singular attribution links and destinations.

The attribution flow is as follows:

  1. The user clicks on an ad served via an ad network's conversion pixel.
  2. The conversion pixel redirects to Singular's attribution tracking link.
  3. Singular saves information about the click and redirects the user to the app store or to a deep link destination.
  4. The user downloads and opens the app.
  5. Singular saves information about the install and attributes the install to the last click on the same device (see Understanding Singular Mobile App Attribution to learn more).
  6. Singular sends out any relevant install postbacks that have been set up.

Snip20180820_55.png

Server-Side (Asynchronous) Attribution

An S2S integration with Singular would follow the same flow, except that the ad network itself redirects the user to the app store or the deep link destination, and Singular click notifications are served by an ad network server or from the client (asynchronously).

The attribution flow is as follows:

  1. The user clicks on an ad served via an ad network's conversion pixel.
  2. The ad network server receives the click, serves a redirect, and sends Singular a click notification.
  3. Singular saves information about the click.
  4. The user downloads and opens the app.
  5. Singular saves information about the install and attributes the install to the last click on the same device (see Understanding Singular Mobile App Attribution to learn more).
  6. Singular sends out any relevant install postbacks that have been set up.

Snip20180819_50.png

 To send Singular clicks from the server side, Singular's tracking link must have these parameters and a value for each that matches what would have been sent from the client / mobile device:

  • "ip" - the raw IP address.
  • "ve" - the device OS version, e.g., "9.2" or "9.2.1" (Not applicable for CTV campaigns.)
  • "p" - the device platform (e.g, android, iOS, or ctv)
  • "redirect=false" - let's Singular know the click is sent S2S

Note: Chrome has released Client Hints meant to reduce User-Agent data starting on February 1, 2023. All traffic initiated from Chrome 110-based browsers (Chrome, Edge, Opera and more) on Android or desktop devices reduces user-agent header data. This means that the complete data is only available upon request.

  • For clicks and impressions reported by the ad network via server-to-server, and impressions reported via the user device, ad networks must use the Client Hints API to request the OS version and IP, and report them to Singular as parameters included in the attribution link so that probabilistic attribution can continue.
  • For clicks reported via the user device, no action is required. Singular has already made necessary adaptations to comply with these changes and retrieves the complete data as required.
  • See more about Client Hints and Singular attribution here.

 

Optional: Appending Google Play Install Referrer (Android Only)

Partners who have a server-to-server integration with Singular's measurement links can append referrer values that can be used in Singular's click-through attribution process.

To enable:

  1. Append and URL-encode the following key-value-pair to the referrer= parameter, to served Play Store URLs:  singular_external_click_id=[partner_name]_[uuid]  For example: https://play.google.com/store/apps/details?id=net.singular.deviceassist&referrer=singular_external_click_id%3Dpartnername_e2675724-0e90-4a80-8123-c3b66a681f3e
    • [partner_name]_[uuid] is the recommended format.
    • [partner_name] can be any agreed-upon value and is a static value used to aid debugging
    • [uuid] should be a UUID, unique per click.
    • Other formats for singular_external_click_id are supported as long as the value is guaranteed to be unique for each click and the length is no greater than 50 characters.
    • Other non-Singular key-value-pairs can be appended to the referrer, but be sure to URL-encode them properly.
  2. Append the singular_external_click_id value (alongside other existing query parameters in the click URL) via the  sng_ref= query parameter in the asynchronous click to Singular's tracking link click URL. For example: https://customer.sng.link/1234/abcd?redirect=false&ip=189.65.238.39&ve=12.5&p=android&sng_ref=partnername_e2675724-0e90-4a80-8123-c3b66a681f3e