Singular FAQs

Singular offers a unique integration with Branch Journeys to track web-to-app conversions accurately using deterministic attribution based on the device's Advertising ID.

If you're using Branch Journeys, it's important to enable this integration so that your web-to-app conversions are tracked correctly in Singular.

For information about deterministic and other attribution methods, see Introduction to Singular Attribution.

Integration Flow

#

Branch processes a click from an organic channel, such as Email or Referral.

When a new user opens the app for the first time, both Singular and Branch process this as a session coming from a new device, and start the attribution flow.

Singular queues the attribution decision until we receive a Branch attribution claim. We receive the claims through webhooks that are configured on the Branch side. When Branch finalizes the attribution decision, it fires a webhook to Singular with the relevant attribution data (e.g., "The iOS device with IDFA=123e4567-e89b-12d3-a456-426655440000 has been attributed to the campaign named 'My Email Campaign'").

Singular incorporates the Branch attribution data into the attribution decision process, along with any other touchpoints collected from both Branch and Singular.

Integration Benefits

Attribution providers typically use click forwarding to process Branch Journeys data. In click forwarding, the attribution provider gets mobile-web device clicks that Branch is tracking. However, this commonly leads to inaccurate attribution.

Singular's Branch Integration provides the following benefits over click forwarding:

Accurate device identification rather than fingerprinting: Mobile web clicks are not associated with the device's Advertising ID (e.g., IDFA), and can only be used for attribution using fingerprinting methods, which are less accurate by nature. In contrast, Branch Journeys does utilize an Advertising ID - which it passes on to Singular through a webhook. Singular can then perform deterministic attribution.

No race conditions: Singular queues the attribution process until Branch reports its final decision, avoiding the risks of attributing before Branch data is received.

Alignment between Singular and Branch: When you use two products to track conversions, it's vital to keep device-level data consistent between the platforms. By using this integration, you ensure that every app install that Branch attributes to a web-to-app conversion is attributed the same way by Singular.

Setup Guide

1. Enable on the Singular Side

This integration is an advanced feature that has to be enabled by Singular's support team. If you are interested in using this integration, please reach out to your Customer Success Manager.

2. Configure a Branch Webhook

In the Branch Dashboard, go to Data Import & Export > Webhooks.

Click Add New Webhook.

Configure a webhook to the URL https://s2s.singular.net/api/v1/s2s/branch, using POST, every time the user triggers the INSTALL event.

3. Test the Integration

Get a new device or reset the Advertising ID on your device. Use the Singular Device Assist app for iOS or Android to retrieve your device's Advertising ID.

Click on a Branch Journey link. Install and open the app.

Wait a few minutes and then open:

In Android:https://api.singular.net/api/attribution/attribution_details?keyspace=aifa&device_id=<YOUR DEVICE'S ADVERTISING ID>

In iOS:https://api.singular.net/api/attribution/attribution_details?keyspace=idfa&device_id=<YOUR DEVICE'S ADVERTISING ID>

You should get a JSON response that looks like the following:

[ { "fingerprint_attribution": false, "tracker_name": "Branch", "network": "Branch", "app_name": "My Awesome App","passthrough": { "pcn": "Branch Campaign Name" } }]

FAQ

How does the Branch integration affect attribution logic?

#

Branch Journeys touchpoints are considered as any other Device ID based clicks:

In the case where a Branch Journeys claim was the only available touchpoint, Singular would use that touchpoint's data for the attribution process.

In the case where there are multiple touchpoints, Singular will defer to the latest one based on its timestamp.

How will Branch attributions look in Singular reports?

#

Branch attributions will show under the Source "Branch" in Singular reports.

Will Singular attributions show up in Branch?

#

No, this integration only handles passing data from Branch into Singular.

Is there a timeout for how long Singular waits for a web-to-app claim from Branch?

Yes, Singular will wait up to 4 minutes, by default.

Learn what the Lookback Window is and how to configure it.

For more Singular attribution concepts, see Introduction to Singular Attribution and Device Fingerprinting Methodology.

The Lookback Window is used to determine how far back the attribution algorithm should search for the matching click of an INSTALL event.

Note: In Singular, the default value of the lookback window is 7 days. You can set it to up to 30 days after an ad was clicked. You can adjust the window in the Partner configuration screen.

In the process of attributing an install to a click, the Singular tracker uses one of several attribution methods (see Singular Attribution ). In addition, it takes into consideration the Attribution Lookback Window to better and more accurately complete the attribution process. This means, that attribution will occur only if the time passed between the click and install is lower than or equal to the Lookback window.

Partner Configuration

For example, in case the lookback window is set to 7 days, and the INSTALL event arrived 3 days after the matching click, the install will be attributed to that click.

If the INSTALL event arrived after 9 days of a click belong to a source that is set with a lookback window of 7 days, the INSTALL will be attributed as Organic.

Notes:

The lookback window can be configured differently for each partner through the page.

If the attribution algorithm finds two matching clicks within the lookback window, the install is attributed to the latest click (the one closer to the install).

If there is no matching click within the lookback window, the install is attributed as Organic, even if there is a matching click outside the window.

Learn how Singular's attribution tracking service works and what it can do.

For more information, see Attribution Lookback Window and Device Fingerprinting Methodology. To learn how to implement Singular Attribution, see Setting Up Singular Attribution: Overview.

Install Attribution

Mobile attribution is the process of connecting actions and activities that occur inside a mobile app to those that occur outside of it.

Singular makes these connections by linking an impression or click action that happens on a device to the install (first session) of a mobile app on that same device.

Methods

Singulars mobile attribution service uses the following methods to attribute installs:

Referrer (Android Only)

This the most reliable attribution method. When a user clicks on an ad and reaches the Google Play store, a unique Singular referral ID is passed to Google Play. Once the user installs the app, the Singular SDK sends the Singular referral ID forwarded by the Play Store, and attribution is performed.

Additionally, Singular uses the same referrer technology to capture other attributions labeled in Singular as UTM Referrer attributions.

Identifier Matching

In this method, the attribution is done based on the Google Advertising ID (AIFA) or iOS Advertising ID (IDFA) that are sent in the tracking link. Once the install event arrives from the Singular SDK, it is matched to the click based on that ID. Identifier matching has a maximum of a 30-day attribution window.

Fingerprint Matching

In this method, a tracking URL collects basic information of the device, including IP address and model, which results in a unique fingerprint. The same fingerprint is generated locally on the device once the app is installed and then sent via Singular SDK session. The click and the session are then fingerprint matched. Fingerprint matching is limited to 24 hours.

Self-Attributing Networks

Using this method, we query special APIs for attribution data of special partners like: Facebook, AdWords, Twitter, Apple Search Ads, Snapchat, Yahoo Gemini.

In accordance with Google and Apple privacy policies, Singular tracks unique devices and their attribution information using the user-resettable Google Advertising ID (AIFA) and iOS Advertising ID (IDFA). Singular retains a devices install attribution information to ensure attribution and cohort accuracy. Re-engagements can be tracked any number of times with supported partners.

Attribution Windows

Singulars install attribution utilizes the attribution windows specified in the partner configuration for all methods except for fingerprint matching. Fingerprint matching uses a default 24-hour window.

Re-engagement Attribution

In re-engagement, users who have already installed the app are actively targeted by a campaign.

Re-engagement attribution is supported for supported click-based partners, as indicated by the the "Enable Reengagement" option when creating tracking links:

Play Store URL with UTM referrers appended

Notes:

Identifiers are available on the generated tracking link. For supported partners, they are passed by the partner in the tracking link via device identifier keys (e.g. idfa=, aifa=). Re-engagement where identifiers are not available (e.g. fingerprinting) is not supported.

Click-based tracking links only. View-through re-engagement is not supported.

For self-attributing networks that do not use tracking tags, make sure re-engagement tracking is enabled in partner configurations.

Attribution Windows

Re-engagement attributions utilize the attribution windows specified in the partner configuration

Event Attribution

Event attribution is based on the devices original attribution source. An event that occurs on the device will be attributed to the source of the devices last attribution, whether it be the install attribution or re-engagement attribution.

For example, consider the following scenario:

install is attributed to "Organic"

a purchase for $5 is made

re-engagement is attributed to "Facebook" within the attribution window

another purchase for $10 is made

The attributed revenue results in the following:

Install - Organic - $5

Re-engagement - Facebook - $10

UTM Referrer Attributions (Android Only)

Android apps with the Singular SDK leverage the Android Referrer API to pass a Singular referral ID for attribution. Attributions to the Singular referral ID are prioritized as they are attributions tracked via Singular tracking links. However, referrer technology also allows Singular to capture attributions from anyone who clicks on a .

Since these are attributions not tracked through a paid source via Singular, UTM Referrer attributions are only counted if no other paid source claims the attribution. UTM Referrer attributions can often offer interesting insights to where additional "Organic" traffic can be coming from. For example, apps downloaded from the app search tab in the Android Facebook app will be tracked in Singular as a "UTM Referrer" attribution to "app.facebook.com".

If you would like to enable UTM Referrer tracking for your Android apps, please reach out to your customer success manager.

Singular Android Uninstall tracking is available with Singular Android SDK 7.x. An app update is required.

Setting Up Uninstall Tracking

Integrate Android SDK 7.x+: Uninstall tracking is available in Android SDK version 7.x and above. For instructions on upgrading your SDK, review our Android SDK integration guide.

Modify AndroidManifest.xml: See the Android SDK uninstall tracking integration guide details.

Add your Sender ID and Server Key: Singular requires a Google Project Number and Server Key for enabling uninstall tracking. To retrieve these values:

Open firebase https://firebase.google.com/.

Select Go to Console and select the project.

Select the gear icon and go to Project Settings.

Select the Cloud Messaging tab.

In your Singular account, go to Settings > Apps, find the app for which you want to track uninstalls, and select Edit.

Under Uninstall Tracking, add the Project Number (Sender ID on Firebase) and Server Key.

Configuring FCM in Your App

Create a Firebase project on the Firebase Console.

After creating the project, It will take you on dashboard from where select the option Add firebase to your Android App.

Provide the package id of Android Application.

Download the config file (google-services.json).

Copy the google-services.json file in app module of Android project.

In Project-level build.gradle (<project>/build.gradle):

buildscript { dependencies { // Add this line or latest version classpath 'com.google.gms:google-services:3.1.0' } }

In App-level build.gradle (<project>/<app-module>/build.gradle):

// Add to the bottom of the fileapply plugin: 'com.google.gms.google-services'

Sync the project.

Create a service in android code (class which will inherit FirebaseInstanceIdService):

public class FCMService extends FirebaseInstanceIdService { @Override public void onTokenRefresh() { super.onTokenRefresh(); //now we will have the token String token = FirebaseInstanceId.getInstance().getToken(); }}

In onTokenRefresh method we will get fcm token that we have to store on our server to send Notifications.

Add this service to the Android Manifest file:

<service android:name=".FCMService"> <intent-filter> <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/> </intent-filter></service>

You can test the notification using the console by providing an FCM token:

Singular will now begin to track uninstalls for users using the updated version of your application.

How Does It Work?

Singular has integrated with Google's services to track uninstalls for your applications, as a proxy measure for the quality of traffic you drive through your paid campaigns. This integration uses a different methodology compared to Google - which reports uninstalls directly from the operating system resident on the device.

A few important points to keep in mind:

Singular and Google use different methodologies to report uninstalls, which results in a variation in numbers. Use the Singular and Google reports separately for their respective purposes.

Uninstalls are tracked as events in Singular and as a result do not remove the attribution link from the originating Install or Re-engagement source. This may result in uninstall rates of higher than 100%, since a user may uninstall an app multiple times in their lifetime.

Learn how to become an integrated partner of Singulars marketing analytics platform. Make sure to read Integrating with Singular: A Guide for Partners first to learn about Singular and the different integration options. See also: Integrating with Singular Attribution.

If you are a Singular customer, see the Data Connectors FAQ instead to learn how to use Singular's existing analytics integrations in your account. See Partner Configuration for information about Singular's attribution tracking integrations.

What is Singular analytics?

Singulars marketing intelligence platform gives advertisers a unified view of all their marketing data in once place in order to empower them to make better decisions.

What Singular does:

Automatically pulls marketing performance data from all of the advertisers ad networks, agencies, and other sources into one database

Combines this data with attribution stats pulled from Singulars native attribution solution or a third-party attribution tracker used by the advertiser

Presents the combined data in dashboards and reports that provide customized performance and ROI insights. The data is presented in a high level of granularity, with breakdowns by app, campaign, targeted country, publisher app, creative, and more).

In order to pull data from all the sources as described above, Singular is integrated with over 1000 companies, including ad networks, agencies, self-attributing networks, BI services, and more. You can browse the full list of partners to get an idea of who we work with.

We keep developing new integrations to meet the needs of our customers - but we need you to help us do it.

What is a Singular analytics integration?

We create analytics integrations (also known as data connectors) when we have a mutual customer that uses you as an ad network, ad agency, or similar service.

The integration is designed to pull the customers aggregated marketing campaign data from you every day in order to present up-to-date data in our analytics reports.

The way we build the connector is highly flexible and depends on the way you present data to your customers. We can pull data from your API if you have one, read it from your dashboard, automatically parse an email report, or even ingest a report file from Google Drive or Amazon S3.

Note:

The integration should be generic - even if it is originally constructed by request of one particular customer, it should be able to serve multiple customers in the future.

Once an integration is set up (e.g. the customer enables the integration in their Singular account and enters their credentials), the integration provides daily data updates automatically, with no further action needed from the user.

What data fields does the integration pull?

Remember that Singulars goal is to combine campaign data and attribution data in order to give the customer a unified, high-granularity report.

For that purpose, we need to get the most detailed breakdown of data we can, both in our analytics integration and our attribution integration.

When you provide reporting data, please include at least the date, campaign, and cost fields - these are mandatory. Singular also supports creative, publisher, and platform breakdowns, and additional metrics such as impressions, clicks, and installs.

How often does the integration pull data?

Singular pulls data daily, and we pull data for the last 7 days.

How does Singular access the data?

Singular uses a number of different methods to integrate with partners:

API Integrations: Singular can pull data from your reporting API. Please note that the API key we use for the integration should be different per customer! We need to be able to pull each customers data separately in order to differentiate the data on our end.

Dashboard-Based Integrations: If you have a reporting dashboard, we can pull the customers data from it.

File-Based Integrations (Email, Google Drive, S3): Singular can ingest data from email reports as well as files shared on Google Drive or S3, if this is how you provide your reports to customers.

How do I become an integrated partner?

1. Gather the necessary information

This depends on the type of integration you want to have with Singular.

Integration Type

Required Information

API Integration

A link to your API documentation that includes the endpoints, supported fields, authentication method, etc. See our Reporting API Guidelines.

Dashboard-Based Integration

Dashboard URL and the customers credentials

File-Based Integration (Email, Google Drive, S3)

We need the email or file to be in a particular structure. To begin, please prepare a sample report in line with our report template. Important:

The mandatory fields are: Date (by day), App name, Campaign Name, Platform or Store ID and the desired metrics.

We also recommend filling in as much information as possible to increase granularity.

If you will not be including data for a certain field, please remove that column from the file entirely instead of leaving it blank.

In the Platform column we support the following values: iOS, Android, iPhone, iPad, Web and Desktop.

2. Fill out the form

Fill out the form to become a Singular partner!

3. Next steps

After you submit the form, we will review it and contact you to let you know if we have any questions or if we have all the information we need.

Then we will create the integration. When were done, well let you know, and we will activate the new integration for the customer.

We will also add the integration to the list of Singular integrations available to customers. Future Singular customers who are also users of your service will also be able to use the integration.

Requirements on your side:

If you will be sharing the report by email with us, please send the first report to <MUTUAL CLIENT NAME>[email protected]

If you will be sharing the report through Google Drive:

Share the report with [email protected]

We pull data from one file per customer only, meaning that the same spreadsheet should be updated with new data every time.

We support data in multiple sheets.

If you will be using S3: Please upload the reports to a dedicated S3 bucket and provide us with the following information:

AWS access_key and secret_key

Relevant bucket names

Learn how to become an integrated partner of Singulars native attribution solution. Make sure to read Integrating with Singular: A Guide for Partners first to learn about Singular and the different integration options. See also: Integrating with Singular Analytics.

If you are a Singular customer, see Partner Configuration instead to learn how to configure integrations with Singular's attribution service. See the Data Connectors FAQ for information about integrations that pull campaign data into Singular.

What is Singular attribution?

One of the products Singular offers is a native attribution solution. Singulars attribution tracker measures the customers mobile marketing performance, including install and re-engagement campaigns.

Singulars customers generate tracking links that incorporate the custom macros of different ad networks used by the customer.

What is a Singular attribution integration?

If you are an ad network or ad agency:

Our mutual customers generate Singular tracking links that incorporate your services custom macros.

You can also receive information from Singular in the form of automated postbacks that notify you about attributed installs, etc.

If you are a third-party analytics platform, BI system, fraud analyzing service, etc:

We send you automated postbacks to let you know about installs attributions and other events identified by Singulars attribution tracker.

How do I become an integrated partner?

Note: If your network is already integrated with Singular, but you would like to verify or update your integration with us, please contact us.

1. Gather the necessary information

Depending on your needs, supported features, and supported platforms, you will need the following for the Singular network integration process:

Your networks macros for values that can be passed in the tracking link:

When we offer the customer the full view of their marketing performance and ROI, we strive to offer the highest granularity - including creative-level and publisher-level breakdowns, when possible.

This is why need as much information as possible about every click on our tracking links. We will ask you to give us your macros for the ad group (ad set), creative ID, publisher app, and more, so we can incorporate these macros in our tracking links.

Your postback preferences and templates:

We currently support three types of postbacks:

Install Postback - Notification of attributed installs

Revenue Event Postback - Notification of revenue events for attributed traffic

Custom Event Postback - Notification of a user's custom event for attributed traffic

To see the available values which Singular can provide in each postback, please see our postback documentation.

Note that any value can be passed back via the postback if designated as a passthrough.

Test devices:

Make sure you have test devices ready (iOS and Android) and their device IDs or advertising IDs.

2. Fill out the integration form

Fill out the form to become a Singular partner!

We will review the form and contact you to let you know if we have any questions or if we have all the information we need.

We will then use the information from the form to integrate your macros and postbacks into Singular tracking link generation tool.

3. Test the integration

After we finish creating the integration, we will contact you to let you know how you can test the integration on your end. We will ask you to try out the test application(s) and device(s) on all the platforms you support. We will check to confirm that both parties have received the proper notifications for clicks and installations as well as any post-install events, including all the appropriate parameters.

Once we confirm the integration works properly, we will activate it for the customer and add your product to the list of Singular attribution integrations that we offer.

Learn what tracking links are, what information they can include, and how to generate them using the Create Tracking Link and Create Custom Tracking Link pages.

Note: This article deals with Singular's legacy tracking links. For help using the new Singular Links, see the Singular Links FAQ.

Tracking links are used to attribute an app installation to an ad click. In addition to basic attribution data, the links can include other properties, which will eventually be displayed in your Singular reports. This data will help give you a ricker view of your marketing efforts and results.

Using Singular you can create two types of tracking links:

Regular Tracking Links - for integrated partners such as AdColony and Chartboost.

Smart Links - for custom marketing sources such as email or SMS campaigns.

Note: Self Attributing Networks, such as Facebook, do not require tracking links. To configure these sources, see Attribution Integrations: Special Instructions.

Understanding Tracking Links

When a potential user clicks on an ad, they are clicking on the tracking link, which sends them to the Singular server before redirecting them onward to the app store. Singular saves the data that was included in the tracking link. Later, if the user installs the app, the Singular attribution service can match the install to the appropriate click.

For more information, see Install Attribution.

Tracking link parameters and report dimensions

Creating a Tracking Link

Link Format

The basic format of a tracking link to be used with the Singular attribution service is as follows:

https://c.singular.net/api/v1/ad?st=[link_id]&h=[link_hash]

Note:

"st" and "h" are tracking link parameters. The more parameters you include, the more data Singular will receive about the users. See below for the full list of parameters.

"[link_id]" and "[link_hash]" are examples of macros. When you include a macro in a tracking link, the ad network replaces it with relevant information in real time when the ad is displayed to the user. Each ad network provides its own macros and is responsible for replacing them with the right data.

For example, the following tracking link includes several macros such as [GOOGLE_AD_ID] and [OS_VERSION]. When a user clicks the ad that contains this tracking link, the ad network will replace the macros with data.

https://c.singular.net/api/v1/ad?st=82228468160&udid=[RAW_UDID]&and1=[SHA1_ANDROID_ID]&aifa=[GOOGLE_AD_ID]&s=[APP_ID]&idfa=[IDFA]&odin=[ODIN1]&udi1=[UDID]&api_key=d4636d565f59e217801b5721af716eac&product_id=[PRODUCT_ID]&ip=[IP_ADDRESS]&ve=[OS_VERSION]&cl=[CLICK_ID]&pc=[RAW_AD_CAMPAIGN_ID]&h=99ebf893909cc390843b2cabc6c4f7eccb567676

In case you find that a tracking link is missing a macro known for a specific source, please contact Singular Support.

Using the "Create Link" Page

The Singular app provides a page where you can enter the information you want to include in the tracking link, and have the link generated automatically with the appropriate parameters and macros.

Go to Attribution > Create Link.

Select the App, Site, and Destination URL (if you are missing a site or destination URL in the drop-down lists, refer to the Apps screen to update the missing data).

If you have selected a deep-link (or Universal Link for iOS), you can optionally mark it to also be used as a deferred deeplink. If your deeplink value is "myapp://page?id=1", then the value received in the SDK callback will be "myapp://page?id=1".

Start typing the Source name and select it from the optional list of sources. If the selected source is not configured yet, a warning message tells you to configure the source. Note that each source may have different configuration options. For more information, see Partner Configuration, Lookback Window, and Events Postbacks.

Enter the Campaign Name and select Generate Link.

Your tracking link is ready. Copy the link using the Copy button.

Using the "Create Custom Link" Page (Create Smart Link)

With Smart Links, you can create a single tracking link that redirects the user to different destinations depending on their device. Smart Links are useful for tracking email/SMS campaigns or any campaign with a non-integrated source.

For example, if you have an email campaign, you may want to include a tracking link with the following redirect behavior:

iOS - take the user to the iTunes App Store

Android - take the user to the Google Play Store

Other - take the user to your web site.

To create a Smart Link:

Go to Attribution > Create Smart Link.

Select the App.

In Source, select one of the offered channels (social, SMS, email, crosspromo) or choose Custom.

Enter the Campaign Name.

Choose the destinations and deeplinks for each platform (iOS, Android, other). Select the Deferred check box to enable deferred deeplink. If your deeplink value is "myapp://page?id=1", then the value received in the SDK callback will be "myapp://page?id=1".

Select Generate Link.

Tracking Link Parameters

Reserved Parameters

Reserved parameters are the standard or common parameters used by the Singular attribution service to properly perform and report attribution with integrated channels and partners.

For a list of the reserved parameters recognized by Singular, see .

Non-Reserved Parameters (Passthroughs)

Occasionally you may see parameters in tracking links which is not a reserved parameter. These parameters are generally used with specific integrations with partners, in order to "pass through" these values to the partner in the attributed postback. While they enable other more advanced use-cases for postbacks, they are not common.

Note: This article deals with Singular's legacy tracking links. For help using the new Singular Links, see the Singular Links FAQ.

Singulars reengagement tracking gives you full control to:

Enable links for retargeting

Create reengagement postbacks for ad networks and third parties

And measure downstream effectiveness of reengagement campaigns along with your acquisition campaigns.

Reengagement tracking is available with ad network partners with reengagement offerings and targeted ads where the device ID is available.

Tracking Links for Reengagements

To track reengagement, turn on Enable Reengagement when you create a link for a partner.

Tip: To track reengagements with partners that don't officially support retargeting, you can enable it by adding "&re=1" to your tracking links. For example, if the original tracking link is:

https://c.singular.net/api/v1/ad?st=XXXX&aifa={aaid}&aif1={gps_adid_lower_sha1}&s={publisher}&idfa={idfa}&ifa1={idfa_upper_sha1}&cl={click_id}&cr={creative}&pc={campaign}&h=XXXXX

After adding "&re=1" you get:

https://c.singular.net/api/v1/ad?st=XXXX&aifa={aaid}&aif1={gps_adid_lower_sha1}&s={publisher}&idfa={idfa}&ifa1={idfa_upper_sha1}&cl={click_id}&cr={creative}&pc={campaign}&h=XXXXX&re=1

Partners that support reengagement campaigns will have additional options available in their Partner Configuration screen, as well when creating Links for them.

Postbacks for Reengagement Attribution

Partners that support reengagement campaigns have additional options available in their Partner Configuration screen.

Reengagement postbacks trigger when a successful reengagement to the partner has been tracked.

As a reengagement, e.g. treating the reengagement as an attribution event. Check "Enable reengagement Postbacks" option for supported partners

While tracking and measuring marketing performance, Singular's attribution service uses postbacks to report installs and events back to the ad networks, for their own measurement.

By default, Singular sends install postbacks to the relevant ad network. In addition, you can send postbacks for any other event, as needed. For example, some ad networks may require a postback for all installs, including installs attributed to other ad networks. Others may require postbacks for post-installation events performed by the user.

You can configure these settings separately for each app through the Partner Configuration page.

contact us

To configure event postbacks:

Select whether events should be sent always, only if the install was attributed to the ad network, or never. Your choice may be dictated by the ad network's requirements.

Click the + sign to add an event.

On the left, select the in-app event as sent from your app to Singular's attribution service. On the right, type the event name as the ad network expects to receive it.

If the event includes a value that you want to deliver to the ad network (for example, an in-app purchase includes a revenue value), select the Send value check box.

Click + and repeat the process until you have added all the events.

If you are missing an in-app event name in a source configuration, please .

Existing device attribution information can be uploaded and brought into the Singular platform!

NOTE: Historical attribution data MUST be imported into your Singular account BEFORE apps are live and used for paid UA campaigns to avoid contamination of historic attributions. If campaigns are started before historical data is loaded, then spikes in Organic installs will occur and the attribution source for some of the devices will be incorrect. To avoid further data contamination, Singular will proceed with loading the remain data as Organic installs. This will still blacklist the historic device for future attributions through new paid UA efforts.

While we understand your existing users' dataset can be formatted in a variety of ways, we require a flat-file of your historical data. To ensure a smooth and speedy import, provide flat files in the format specified below.

Please note that we only support importing devices with advertising IDs (IDFA or AIFA).

If data is not provided in this format, delays in processing or rejection of the file can occur. Singular will examine the data files provided and inspect for duplicate installs. If duplicates are found, the duplicates will be removed and a file with unique advertising IDs will be used for the data on-boarding.

File Type

Provide data files on one of the two formats below:

unix encoded '.tsv' (tab separated file)

unix encoded '.csv' (comma separated file)

File Naming Convention

Use the following naming convention to keep your data files organized.

Provide one file per App.

Filename Examples:

Date file is provided (YYYYMMDD)_App-Name_installs.tsv 20170115_my-app-name_singular_installs.tsv

File Column Layout with data (Historical Installs)

Column Name

Required

Column Description

Sample Data

app_id

Y

Apps package name/bundle ID for Android/iOS respectively

com.singular.app

os

Y

Android or iOS

Android or iOS

idfa

Y

iOS ID for Advertisers

DFC5A647-9043-4699-B2A5-76F03A97064B

idfv

iOS ID for Vendors

21DB6612-09B3-4ECC-84AC-B353B0AF1334

gaid

Y

Google Advertising ID

8ecd7512-2864-440c-93f3-a3cabe62525b

android_id

Android ID

fc8d449516de0dfb

device_ip

IP Address of the Device at Install

168.144.2.3

country

2-Letter Country Code of the Install

US

install_time

Y

Time or First App Open in Epoch Unix Format

1483228800

source

Ad-Network that drove the install ex. Facebook, AdWords, Vungle

Vungle

campaign_name

Campaign on that network

RON_Campaign_iOS

creative_name

Creative on that network

Creative_A

user_id

Custom User ID

player_1234

dnt

Pass 1 if do not track is enabled, 0 if do not track is disabled. (aka Limited Ad Tracking)

0

You can set up Singular to track uninstalls for your iOS app. Uninstall tracking is available with Singular iOS SDK 8.x and above, and to start using it you will need to update your app.

Setting Up Uninstall Tracking

To start tracking uninstalls:

1. Integrate (or update to) Singular iOS SDK 8.X

For instructions on upgrading your SDK, see our iOS SDK integration guide.

2. Update your iOS app to support Applepush notifications and pass the APNS device token to the Singular SDK

Singular requires an Apple Push Notification Certificate to enable uninstall tracking for iOS. If this is your first time setting up push notifications for your iOS app, see Apple's documentation. Once your app supports Apple push notifications, follow the Singular iOS SDK Implementation Guide to enable the Singular SDK to track uninstalls.

Note: In accordance with Apple's policies, your app's users will be asked to opt in to receive push notifications. Singular will only be able to track uninstalls for users who have opted in. In the future, Singular will support tracking how many of your installed users can be included in uninstall tracking.

3. Add your Apple Push Notification Certificate to your iOS application page in Singular

To retrieve your certificate and upload it into Singular:

Create and download an Apple Push Notification SSL certificate: In your Apple developer account, navigate to Certificates, Identifiers & Profiles > Identifiers > App IDs. In your Application Services View, you can configure push notifications for both your Development and Production builds.

Note that while you can use your Development certificate for your own internal testing, Singular uninstall trackingrequires the Production SSL certificateto be used with your live app.

Generate a PEM (.p12) file from your Keychain: After you've downloaded your certificate, double-click on it to add it to your Mac Keychain, where it is paired with a private key.

Selectboth the certificate and private key,right click, and export to a .p12 file with a meaningful name.

Upload your .p12 file into your iOS apps' application page underUninstall Tracking, and enter in the password for your .p12 certificate from above.

A few important points to keep in mind:

Singular use of Apple push notification services does not actually cause a push notification to appear for the end-user

Uninstall tracking is only available for users who have enabled push notifications for your app

Uninstalls are tracked as events in Singular and as a result do not remove the attribution link from the originating Install or Re-engagement source. This may result in uninstall rates of higher than 100%, since a user may uninstall an app multiple times in their lifetime.

To enable sending Push Notifications through APNs, you need:

an SSL certificate associated with an App ID configured for Push Notifications.

a provisioning profile for that App ID.

You create both in the Apple Developer Member Center.

Creating the SSL Certificate

This section describes how to generate an SSL certificate for an App ID enabled for Push Notifications. GCM will use this certificate to send Push Notifications to the application identified by the App ID.

Generating a Certificate Signing Request File

To authenticate the creation of the SSL certificate, you need a certificate signing request file.

Note: You create the certificate signing request file on your Mac.

Open Keychain Access on your Mac (you can get to it by choosing Utilities from the Go menu in the Finder).

On the Keychain Access app menu, navigate toKeychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority...

Input your email address and name.

ForRequest isselectSaved to disk, then clickContinueto save the file ".certSigningRequest" to your Mac.

Apple Developer Member Center

Creating an App ID

An App ID is an identifier that uniquely identifies an app. As a convention, it is represented by a reversed domain (e.g.com.google.samples.gcmexample).

If you already have an App ID that you would like to use, make sure that it is an explicit App ID (it does not contain a wildcard) and skip this section.

Navigate to the Apple Developer Member Center and sign in.

Navigate toCertificates, Identifiers, and Profiles.

In the drop-down menu on the top left corner, selectiOS Apps, then navigate toIdentifiers.

Click the+button to create a new App ID.

To create the new App ID:

Input aNamefor your App ID (e.g.GCM Sample App)

Choose anApp ID Prefix(the default selection should be fine)

In theApp ID Suffixsection, selectExplicit App ID, then input yourBundle ID(e.g.com.google.samples.gcmexample). The value of the Bundle ID should match the value that you are using in your app'sInfo.plistand the value that you are using to get a configuration for GCM.

In theApp Servicessection, make sure thatPush Notificationsis checked.

ClickContinueand check that your input is correct:

The value ofIdentifiershould match the concatenation of the values of the App ID Prefix and of the Bundle ID

Push Notificationsshould beConfigurable

ClickSubmitto create the App ID.

Configuring an App ID for Push Notifications

To send Push Notifications to an iOS App, you must configure its App ID to do so.

In the list of iOS App IDs, select the one you want to use, then clickEdit.

In thePush Notificationssection, you can create a Client SSL certificate for the development or production environment. Create one for development clickingCreate Certificate...in theDevelopment SSL Certificatesection.

You should now see a section calledAbout Creating a Certificate Signing Request (CSR)that contains information about creating a CSR. ClickContinue.

You should now be in theGeneratesection of the flow. ClickChoose File...and select the.certSigningRequestfile that you created before, then clickGeneratewhen it becomes active.

When the SSL certificate is ready, clickDownloadto save it to your Mac, and clickDoneto close the certificate creation flow.

On your Mac, locate the downloaded SSL certificate and double-click it to install it in your keychain.

On your Mac, open Keychain Access. UnderMy Certificates, locate the certificate that you have just added; it should be calledApple Development IOS Push Services: your.bundle.id.

Right-click on the certificate, selectExport Apple Development IOS Push Services: your.bundle.idand save it as a.p12file. Enter a password to protect the exported certificate if you want.

The app is now enabled to use the Push Notification development environment. When you are ready to release your application, you need to enable the app to use the Push Notification production environment: repeat these steps, but clickCreate Certificateunder theProduction SSL Certificatesection instead ofDevelopment SSL Certificate.

Note: In your code, make sure that the value of thekGGLInstanceIDAPNSServerTypeSandboxOptionoption that you are passing to GGLInstanceID.tokenWithAuthorizedEntity:scope:options:handler: is correctly set for the environment that you are using:truefor development,falsefor production. If you are not using the correct environment, messages will not be delivered to your app.

Creating the Provisioning Profile

To test your app while under development, you need a Provisioning Profile for development to authorize your devices to run an app that is not yet published on the App Store.

Navigate to theand sign in.

Navigate toCertificates, Identifiers and Profiles.

In the drop down menu on the top left corner, selectiOS Apps, then navigate toProvisioning Profiles.

Click the+button to create a new Provisioning Profile.

SelectiOS App Developmentas provisioning profile type, then clickContinue.

In the drop down menu, select the App ID you want to use, then clickContinue.

Select the iOS Development certificate of the App ID you have chosen in the previous step, then clickContinue.

Select the iOS devices that you want to include in the Provisioning Profile, then clickContinue. Make sure to select all the devices you want to use for your testing.

Input a name for this provisioning profile (e.g.GCM Sample App Development Profile), then clickGenerate.

ClickDownloadto save the Provisioning Profile to your Mac.

Double-click the Provisioning Profile file to install it.

As a user of the Singular attribution service, you can access your raw user-level data through the Export Logs page.

To export a log:

Go to Attribution > Export Logs.

Choose the relevant date range. You can see up to three months of data with this tool.

Select the app, the app site, and the type of records you want to export (clicks, installs, events, or postbacks).

Select the fields you want to include by dragging them into the Selected Fields box.

Optionally, you can filter the log by:

Partners

Countries

Events

Select Export Log.

Notes:

The current export is limited to 5M records per request. We suggest limiting your date range (i.e. to a single day) in order to prevent reaching this limit.

If you would like to change the list of fields exported by default in your log export, or add a request for a new field to be exported, feel free to contact your account manager.

The timestamped fields (e.g. touchpoint__timestamp) will be exported in your configured timezone. Timestamps that are unix-time based (e.g. touchpoint__unix_timestamp) are in the UTC timezone.

Supported Fields per Event Type

Clicks

Field Name

Meaning

Example

GAID SHA1

The sha1 of the gaid of the touchpoint

ffa6706ff2127a749973072756f83c532e43ed02

GAID MD5

The md5 of the gaid of the touchpoint

128ecf542a35ac5270a87dc740918404

GAID

The Google Advertising Id of the touchpoint

dcd84702-d175-41ab-adfa-9f4ff9d49316

Android ID SHA1

The sha1 of the aid of the touchpoint

ffa6706ff2127a749973072756f83c532e43ed02

Android ID MD5

The md5 of the aid of the touchpoint

128ecf542a35ac5270a87dc740918404

Android ID

The Android Id of the touchpoint

dcd84702-d175-41ab-adfa-9f4ff9d49316

App Longname

The app longname of the touchpoint

com.example.amazing_app

Extra

The extra fields of the touchpoint

redirect=false&rt=json&game_id=123233

IDFA

The idfa of the touchpoint

dcd84702-d175-41ab-adfa-9f4ff9d49316

IDFV

The idfv of the touchpoint

>dcd84702-d175-41ab-adfa-9f4ff9d49316

IDFA SHA1

The sha1 of the ifa of the touchpoint

ffa6706ff2127a749973072756f83c532e43ed02

IDFA MD5

The md5 of the ifa of the touchpoint

128ecf542a35ac5270a87dc740918404

IP

The IP address of the touchpoint

10.20.30.40

Is Re-engagement

If the touchpoint was drove by a re-engagement campaign

true/false

Campaign

The partner campaign of the touchpoint

128ecf542a35ac5270a87dc740918404

Campaign ID

The partner campaign id of the touchpoint

Chartboost_IOS

Campaign Name

The partner campaign name of the touchpoint

Charboost_Example_IOS

Click ID

The partner click id of the touchpoint

128ecf542a35ac5270a87dc740918404

Creative

The partner creative of the touchpoint

EMEA_30seconds_LUKE

Creative ID

The partner creative id of the touchpoint

128ecf542a35ac5270a87dc740918404

Creative Name

The partner creative name of the touchpoint

EMEA_30seconds_LUKE

Partner

The partner name (network name) of the touchpoint

Facebook

Publisher

The partner publisher of the touchpoint

1235551

Publisher Concatenated

The partner publisher (concat) of the touchpoint

1235551

Publisher ID

The partner publisher id of the touchpoint

1235123

Publisher Name

The partner publisher name of the touchpoint

My Awesome App

Sub Campaign

The partner sub campaign of the touchpoint

Charboost_Example_IOS

Sub Campaign ID

The partner sub campaign id of the touchpoint

1511

Sub Campaign Name

The partner sub campaign name of the touchpoint

Non-Incent KR

Sub Publisher

The partner sub publisher of the touchpoint

15511

Sub Publisher ID

The partner sub publisher id of the touchpoint

321291

Sub Publisher Name

The partner sub publisher name of the touchpoint

Sub Pub

Platform

The platform of the touchpoint

ios

Timestamp

The ISO 8601 formated timestamp of the arrival of the touchpoint to the Singular servers

2018-02-26T12:55:38+00:00

Timestamp Unix UTC

The UTC unix timestamp of the arrival of the touchpoint to the Singular servers

1519646873

Tracker Name

The singular tracker name of the touchpoint

Google Display (Apps)

Singular Campaign Name

The Singular campaign name of the touchpoint

12323534543 - AdWords_EMEA

Security Hash

The Singular security hash of the touchpoint

ffa6706ff2127a749973072756f83c532e43ed02

Tag ID

The Singular tag id of the touchpoint

123123125543

touchpoint__udid

The udid of the touchpoint

2b6f0cc904d137be2e1730235f5664094b831186

UDID

The UTC unix timestamp of the arrival of the touchpoint to the Singular servers

1519650478

User Agent

The user agent of the touchpoint

Mozilla/5.0 (iPhone; CPU iPhone OS 11_0_3 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Mobile/15A432

Installs

Field Name

Meaning

Example

App Longname

The app longname of the event that drove the attribution

com.example.amazing_app

App Version

The app_version that the event that drove the attribution originated from

2.5

City

The city that the event that drove the attribution originated from

Bangkok

Country

The country that the event that drove the attribution originated from

FR

Custom User ID

The advertiser's custom user ID to align user device IDs with internal schema

########

Device ID

The device id of the event that drove the attribution

dcd84702-d175-41ab-adfa-9f4ff9d49316

Device ID Type

The device id type of the event that drove the attribution

idfa

Device Make

The make of the device that the event that drove the attribution originated from

Apple

Device Model

The model of the device that the event that drove the attribution originated from

iPhone8,1

IDFV

The IDFV of the event that drove the attribution

dcd84702-d175-41ab-adfa-9f4ff9d49316

Install Source

The app store that was used for the install

com.amazon.venezia

OS Version

The operating system version of the event that drove the attribution

9.3.5

State

The state that the event that drove the attribution originated from

South Carolina

Event Timestamp

The ISO 8601 formatted timestamp of the event that drove the attribution in the customer's timezone

2018-02-25T00:55:08.000-05:00

Event Timestamp Unix UTC

The Unix timestamp of the event that drove the attribution in UTC timestamp

1519570010

Google Click ID

The Google Click ID (in cases of Google AdWords attribution)

CJjsqefUkAJSHDJ_gPdDiEAAA

Is Fingerprinted

If the attribution method is "fingerprinting"

true/false

Touchpoint IP

The IP of the touchpoint that drove the attribution

90.80.70.60

Is Re-engagement

If the touchpoint of the attribution was driven by a re-engagement campaign

true/false

Creative

The partner creative of the touchpoint that drove the attribution

EMEA_30seconds_LUKE

Partner

The partner name (network name) of the touchpoint that drove the attribution

Chartboost

Publisher Concatenated

The partner publisher (concat) of the touchpoint that drove the attribution

4368483

Bid Type

The pricing model set in the partner of the touchpoint that drove the attribution

CPM

Tracker Name

The singular tracker name of the touchpoint that drove the attribution

MM_18-22_2018-01-24

Singular Campaign Name

The singular campaign name of the touchpoint that drove the attribution

12323534543 - AdWords_EMEA

Touchpoint Timestamp

The ISO 8601 formatted timestamp of the touchpoint that drove the attribution in the customer's timezone

2018-02-25T00:55:08.000-05:00

Touchpoint Timestamp Unix UTC

The Unix timestamp of the touchpoint that drove the attribution in UTC timestamp

1519549529

Events

Field Name

Meaning

Example

Adjusted Timestamp

The ISO 8601 formatted timestamp of the event in the customer's timezone. If the event was generated more than 24 hours ago (more than 24 hours of "lag"), the lag will be maxed to 24h, so the event will be assigned to "yesterday")

2018-02-25T07:03:59+00:00

Adjusted Timestamp Unix UTC

The UTC Unix timestamp of the event. If the event was generated more than 24 hours ago (more than 24 hours of "lag"), the lag will be maxed to 24h, so the event will be assigned to "yesterday")

1519553362

App Longname

The app longname of the event

com.example.amazing_app

Args

The arguments sent with the event

{"pcc":"AED","r":36.990001678466797}

Custom User ID

The advertiser's custom user ID to align user device IDs with internal schema

#######

Device ID

The device id of the event

dcd84702-d175-41ab-adfa-9f4ff9d49316

Device ID Type

The device id type of the event

idfa

IP

The IP address of the event

10.20.30.40

Name

The name of the event

Purchase

OS Version

The operating system version of the event

11.0.3

Server Timestamp

The ISO 8601 formatted timestamp of the arrival of the event to the Singular servers in UTC

2018-02-25T07:03:59+00:00

Server Timestamp Unix UTC

The UTC Unix timestamp of the arrival of the event to the Singular servers

1519555642

Session ID

The session id of the event

dcd84702-d175-41ab-adfa-9f4ff9d49316

Revenue

Populated if event is a revenue event. The revenue amount, in currency type "Currency"

43.20

Currency

Populated if event if a revenue event. The ISO-4217 3 digit currency code corresponding to the amount of revenue in "Revenue"

USD

Is Revenue Receipt Included

For revenue events, indicates whether we got a receipt in this event or not

1

Is Revenue Valid

For revenue events, is the revenue valid (if IAP validation is enabled)

TRUE

Received Revenue

For rejected revenue events, the amount of revenue reported originally

0.99

Received Revenue Event

For rejected revenue events, the name of the revenue event reported originally

Purchase1

Postbacks

Field Name

Meaning

Example

Is Attributed Only

If the postback is attributed only

true/false

App Longname

The app longname of the event that drove the attribution, of the attribution that drove the postback

com.example.amazing_app

Platform

The platform of the event that drove the attribution, of the attribution that drove the postback

ios

Event Timestamp

The ISO 8601 formatted timestamp of the event that drove the attribution, of the attribution that drove the postback, in the customer's timezone

2018-01-26T04:55:17.000-05:00

Creative

The partner creative of the touchpoint that drove the attribution

EMEA_30seconds_LUKE

Partner

The partner name (network name) of the touchpoint that drove the attribution

Facebook

Publisher Concatenated

The partner publisher (concat) of the touchpoint that drove the attribution

13540

Tracker Name

The singular tracker name of the touchpoint that drove the attribution

MM_18-22_2018-01-24

Singular Campaign Name

The singular campaign name of the touchpoint that drove the attribution

12323534543 - AdWords_EMEA

Install Timestamp

The ISO 8601 formatted timestamp of the touchpoint that drove the attribution in the customer's timezone

2017-12-13T14:22:57.000-05:00

Postback HTTP Body

The HTTP body of the postback

{}

Postback Timestamp

The ISO 8601 formatted timestamp of the creation of the postback in the customer's timezone

2018-02-25T00:53:12.000-05:00

Postback Timestamp Unix UTC

The UTC Unix timestamp of the creation of the postback

1519559807

Device ID

The device id of the event that drove the postback

dcd84702-d175-41ab-adfa-9f4ff9d49316

Device ID Type

The device id type of the event that drove the attribution

idfa

Is Do Not Track

If the event that drove the postback is marked as "do not track"

true/false

Event Name

The name of the event that drove the postback

__SESSION__

Event Timestamp Unix UTC

The UTC Unix timestamp of the event that drove the postback

1519544339

Target URL

The URL that the postback was sent to

recipient.com

Response HTTP Body

The HTTP response body of the postback sent

{\\"is_fb\\":false}

Response Time

The interval, in seconds, that it took for the HTTP response of the postback

141

HTTP Retries Count

The number of HTTP retries of sending the postback

0

Response HTTP Code

The HTTP response status of the postback sent

200

Postback Recipient

The recipient of the postback

Google AdWords

Postback Sent Timestamp

The ISO 8601 formatted timestamp, of the send, of the postback in the customer's timezone

2018-02-25T00:07:45.000-05:00

Postback Sent Timestamp Unix UTC

The UTC Unix timestamp, of the send, of the postback

1519563810

Postback Type

The type of the postback (event/attribution)

event

Is Revenue Receipt Included

For revenue events, indicates whether we got a receipt in this event or not

1

Is Revenue Valid

For revenue events, is the revenue valid (if IAP validation is enabled)

TRUE

Received Revenue

For rejected revenue events, the amount of revenue reported originally

0.99

Received Revenue Event

For rejected revenue events, the name of the revenue event reported originally

Purchase1

Note: This article deals with Singular's legacy tracking links. For help using the new Singular Links, see the Singular Links FAQ.

Tracking Links use destination URLs to manage all of the different URLs a user can land on. To change the destination URLs for an app's tracking links, you would usually go to Settings > Apps in the Singular platform. However, if the need arises to override a destination URL through the tracking link itself, you can do so using the murl parameter.

Note: The URL created using this method will be used for all users, regardless of their platform and install state. Use this method only if absolutely necessary.

To override a tracking link's destination URLs:

URL-encode your Destination URL. For example, the deeplinkapidmgr://forget_deviceresults in the encoded URL apidmgr%3A%2F%2Fforget_device

Append the following parameter to your SmartTag:

&murl=<encoded URL from step 2>

For example, you can update a SmartTag to send all users to the deep link from step 2 above:

https://c.singular.net/api/v1/ad?re=1&st=871332383153&h=71da783132999f0eee204c0d687365bf484c5d&murl=apidmgr%3A%2F%2Fforget_device

Note: This article deals with Singular's legacy tracking links. For help using the new Singular Links, see the Singular Links FAQ.

You can declutter your View Links page by archiving old tracking links that are no longer relevant. You can also edit links if you mislabeled them.

Archiving Links

To archive a link:

Go to Attribution > View Links.

To archive an entire network, hover over the network, and click on the file icon to archive.

To archive a specific link, click into the network, then hover over the campaign name, and click on the file icon to archive.

Note: Archived links are not deleted - they are only hidden from view in the View Links page. Clicks associated with the links are still recorded and attributed as normal.

Editing Links

To edit a link:

Go to Attribution > View Links.

To edit a specific link, hover over the network, then hover over the campaign name, and click on the pencil icon to edit link.

Learn how to avoid data discrepancies when using both the Facebook SDK and the Singular SDK/S2S in the same app.

For more onboarding information, see Integrating the Singular SDK and Facebook Setup.

If you have the Singular SDK integrated in your app, youdon'tneed to integrate the Facebook SDK in order to track Facebook attribution or view events in the Facebook platform. Because Singular is a certified Mobile Measurement Partner of Facebooks, the Singular SDK can take care of all that for you.

However, some Singular customers may still choose to integrate the Facebook SDK in their apps for various reasons. For example, you may use the Facebook SDK to provide Login or Share, or to take advantage of the advanced capabilities of Facebook Mobile App Install Ads.

If you do wish to use the Facebook SDK, it is important to follow the steps below in order to maintain data accuracy across both platforms. Otherwise you may encounter data discrepancies including an increased session count on Facebooks platform and a double event count on Facebook.

To Use the Facebook SDK with the Singular SDK/S2S:

Disable Facebook SDK sending events. By default, the Facebook SDK sends events automatically to the Facebook platform. To disable this, follow the explanation under Disable Automatically Logged Events in the Facebook Developers Portal:

Instructions for iOS

Instructions for Android

Set up Facebook attribution tracking as explained in our Facebook setup guide, steps 1-4.

Use the Partner Configuration page to tell the Singular attribution tracker which networks and services to work with.

To pull campaign data from networks so you can analyze it with Singular reports, you need to set up those networks separately in the Data Connectors page. See the Data Connectors FAQ for more information.

If you are a Singular partner or want to become one, see Information for Partners instead.

When configuring a partner for use with the Singular attribution service, you will need to fill out some partner-specific fields that are required by the partner. The configuration varies between partners as well as between different apps in one network. The source for each app has to be configured once and can be updated later.

Also see Special Partners below for instructions for configuring some partners, such as Facebook and Twitter.

To configure a partner for use with the Singular attribution service:

Go to Attribution > Partner Configuration.

Use the filtering box on the top left to search for the partner you want to configure.

Select Add site, or click the partner to display a list of configured sites and select the Edit button. Read more about Chartboost

Partner configurations can also be exported.

Exporting a partner configuration will download a .csv file with the following information:

"Partner" - The recipient of the postback

"App" - The display name of the app

"Long Name" - The longname or bundle ID of theapp

"OS" - The OS of the app, iOS or Android

"Created" - The timestamp of the created postback

"Click-through attribution lookback window" - The lookback window used for event postbacks. For example, a lookback window of 5 days for an attributed "ViewProduct" event will cause an attributed "ViewProduct" postback to trigger, only if it came within 5 days of the attributed click.

"Postback Type" - The postback type, install or event

"Events" - The name of the event which will trigger the postback

"Attributed Only" - If the postback will trigger only on attributed events, or all events

"Postback URL" - The URL, with Singular macros, of the postback that will trigger.

You can also configure a partner while you are creating a tracking link in the Attribution > Create Link page:

When you select the source (network) to generate a tracking link for, you get a link to configure the source.

If the source you select is not configured yet, an alert tells you to configure the source.

The Configuration Window

Configuring App-Specific Parameters

The Configuration window displays different fields based on the authentication required by the specific source.

For example, when setting up Vungle as a partner, you may see the following fields:

When setting up Chartboost as a partner, you may see the following:

Configuring the Attribution Lookback Window

The lookback window determines how far back the attribution algorithm should search for the matching click of an install event.

If the window is set to 7 days (the default value), and the install event is recorded 3 days after the matching click, the install is attributed to that click. If the install event happens 9 days after the click, it is not attributed to the click (and instead is recorded as an Organic Install).

Note: If there are two matching clicks for an install event, the install is attributed to the closest click.

Configuring In-App Event Postbacks

Some partners require the attribution service to send them postbacks to notify them about events that happen after the install.

For these partners, you will see fields such as follows:

First, select the frequency in which you would like to send in-app events to the partner:

All - send to this source all the event postbacks arriving from all the sources.

Only if install was attributed - send only the postbacks of and attributed install of this source.

Off - Never send event postbacks to the source

Next, map your in-app events:

Select the In-App (SDK) Event Name according to the name used in the SDK, and map it to the Event Name (or event ID) provided by the partner.

Check the Send Revenue check box for relevant events. If the box is not checked, the postback will only send counts of the event.

Configuring Re-Engagements Postbacks

Depending on the partner, you may need the Singular attribution service to send the partner postbacks when it recognizes a successful re-engagement.

For partners that support re-engagement, a re-engagement postback can be configured to notify the partner of a successful re-engagement attribution. To do this, check the Enable Re-Engageent Postbacks option which is available for supported partners only.

Special Partners

Facebook: No configuration is required. Read more about Facebook attribution.

Adwords: Learn about configuring Adwords as a partner.

Twitter: Learn about configuring Twitter as a partner.

Apple Search Ads: Learn about configuring Apple Search Ads.

Snapchat: Learn about configuring Snapchat.

Chartboost: Since Chartboost requires receiving postbacks for all installs, you must check the box Send postbacks to Chartboost on all installs in order to save the configuration. .

Learn everything you need to do in order to get Singular attribution tracking working for your app.

For more information about using the Apps settings page, see App Configuration.

To set up your apps for attribution, follow the instructions below:

Start by integrating the Singular SDK into your app.

In the Singular platform, go to Settings > Apps and select the app site that you want to configure.

Configure the Store URL.

Optional: Configure Destination URLs.

Optional: Configure Uninstall Tracking.

Optional: Configure Deep-Link URLs.

Optional: Configure Universal App Links (iOS Only).

Optional: Group your Apps.

Configure the Store URL

The Store URL is used to redirect your customers to the right location to download your app.

iOS Universal Links FAQ

Note: For Android, Singular automatically finds the right URL based on your package name - no extra step is needed.

Optional: Configure Destination URLs

It is possible to set a few different destination URLs in addition to the default store URL. Use this option when you need a campaign to redirect a user to a different URL than the default store URL, for example:

When you have custom landing pages or websites

When you use an app store A/B testing solution such as StoreMaven

During the process of Generating Tracking Links, you can select each one of the configured destination URLs to be targeted by a tracking link.

To create a new destination URL:

Select the app and then select the app site you want to configure.

Click on the + sign next to the Destination URLs and type your new destination URL.

Click Save.

Optional: Configure Uninstall Tracking

Uninstall rate can be a good metric to track as an indicator of low-value users who uninstall your application after installing it.

To enable uninstall tracking, see Getting Started with iOS Uninstall Tracking and Getting Started with Android Uninstall Tracking.

Optional: Configure Deep-Link URLs

Deep-links can help drive returning users directly to the heart of your application. You can create URIs that that automatically load your application to a specific screen when clicked.

After configuring your application to handle URIs, you can create deep links like these:

Deep-Link Example

Use

SampleApp://

Launch application

SampelApp://search?product=123

Open to search results for a specific item

SampleApp://user

Open the app to the user's profile page

SampleApp://LastLevel

Load last level user attempted

When combined with targeted campaigns, deep linking allows you to seamlessly re-engage users into your application.

To configure a new deep-link URL:

Click on the app and then on the relevant site you would like to configure.

Click on the + sign next to the Default Link URLs and type your new deep-link URL.

Click Save.

For more information, see our Deep-Linking FAQ and Singular Links FAQ.

Optional: Configure Universal App Links (iOS Only)

Universal Links is an Apple deep-linking technology introduced and available only to devices on iOS 9 and above. It is a technology meant to replace the traditional URL scheme deep-linking, and to address the need for serve the best user experience to iOS app users regardless of if the app is present on the device.

For more information about Universal Links and how to enable them for your apps in Singular, see the .

Optional: Group Your Apps

Often, your apps have multiple versions for different platforms - for example, iOS and Android versions. In Singular, each version is defined as an app site, but you can group them together under the same app.

Grouping versions together allows for:

Creating smart links - Links that automatically redirects your users to the right app store based on the device type

Smarter Reporting - Group your reportings by the App / Game name.

If you have created separate app sites and you want to move them into the same app, do the following:

Click on the app site that you want to move and then click on the Move to button.

Choose the destination app.

Delete the old app by clicking on the trash can icon.

Learn about the two types of attribution integrations Singular offers. Make sure to read Integrating with Singular: A Guide for Partners first, as well as Integrating with Singular Attribution FAQ (Partners).

Client-Side Attribution

A client-side attribution is the most commonof the mobile attribution integrations. This is the recommended integration method with Singular. It allows the advertiser to use their configured destinations in Singular and enables full use of Singular SmartTag and destinations.

The attribution flow is as follows:

User clicks on an ad which servedvia an ad network's conversion pixel.

The ad network conversion pixel redirects to Singular's attribution tracking URL.

Singular tracks the click and serves a redirect to the app store or a deep-link.

User downloads and opens the app.

The install is tracked by Singular and the last click for the device is awardedthe attribution.

Any configured install postbacks are distributed.

Server-Side Attribution

An S2S integration has the same flow as a client-side attribution, with the exception that the ad network performs the app store or deep-link redirect, and Singular click notifications are served by an ad network server.

The attribution flow is as follows:

User clicks on an ad which servedvia an ad network's conversion pixel.

The ad network server receives the click, serves a redirect back to the device, and sendsSingular a click notification.

Singular tracks the click.

User downloads and opens the app.

The install is tracked by Singular and the last click for the device is awardedthe attribution.

Any configured install postbacks are distributed.

In order to send Singular clicks from server-side it is mandatory to append IP address and OS version using these parameters:

"ip" - raw IP address

"ve" - version of the OS on the device ( e.g 9.2)

Always append "&redirect=false" to the tracking link.

Learn how to integrate with Singular through the Singular Reporting API. For more information, see the full API reference for developers.

If you are a Singular customer, see Introduction to the Singular Reporting API instead. See also: Reporting API: FAQ and Troubleshooting and Reporting API: Best Practices.

This article gives some API usage examples for partners who want to integrate with Singular via the Singular Reporting API.

The examples below how to retrieve campaign metrics for an advertiser based on specified breakdowns and filters.

Basic Rules

API Response Format: JSON or CSV (the response format that you would support)

Method: GET (Singular will retrieve the data from your API)

API endpoint: please share with us your API endpoint

Query Parameters

Name

Required

Query Parameter

Description

Examples

start_date

Yes

Date

Start Date

2018-01-01

end_date

Yes

Date

End Date

2018-01-02

Dimensions

Minimum requirements in order to start integration - date(daily breakdown date), campaign name and cost. We support multiple granular dimensions, please find them below.

Name

Description

Examples

date

Date

2018-01-01

app

Advertiser App Name / Site Name

2018-01-02

site_public_id

Site Public ID (Store ID)

campaign_name

Campaign name as reported by the Network

campaign_id

Campaign ID as reported by the Network

campaign_url

Campaign URL (Tracking URL/Store URL)

sub_campaign name

Sub-campaign (e.g., Ad Group) name when applicable

sub_campaign_id

Sub-campaign (e.g., Ad Group) ID when applicable

country

Country

platform

Platform (e.g iPhone) for the app

iPhone, iPad

os

The operating system for the app. Non-mobile this would be web

iOS, Android, Web

creative_name

Creative Name

creative_id

Creative ID

creative_url

The URL to the creative assets (Image/Video)

creative_text

The text portion of the creative, if there is text

creative_width

Creative width in pixels

creative_height

Creative height in pixels

publisher_site_name

The name of the publisher (app) in which the ad has been displayed. This is only populated in cases where the ad network reports it.

publisher_site_id

The public ID of the publisher (app) in which the ad has been displayed. This is only populated in cases where the ad network reports it.

publisher_id

The hashed ID of the publisher (app) in which the ad has been displayed

currency

Currency

adnetwork_name

Ad Network Name (Only for Agencies)

Metrics

Name

Description

Examples

impressions

Impressions reported by the Network

clicks

Clicks

installs

Installs or Conversions

cost

Cost reported by the Network

Examples

Assuming your report API token is 4ru34ur3u4u5i3pteqrt

Request:

GET

https://api.partnername.net/api/v2.0/reporting/4ru34ur3u4u5i3pteqrt?start_date=2018-01-01&end_dat e=2018-04-01

The response is in CSV.

Date,campaign_name,site_public_id,os,creative_name,creative_id,creative_url,Impressions,Clicks,Installs,Cost2018-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,interstitial,3,http://partnername.net/interstitials4.jpg,292088,11244,238,166.6 2018-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,banner,2,http://partnername.net/banner2.jpg,16444743,86716,4366,3056.2 2018-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,banner,1,http://partnername.net/banner1.jpg, 802797,40263,1800,3960.0 2018-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,video,3,http://partnername.net/video3.jpg,398590,17107,763,2479.75 2018-01-01,Fresh Air iOS Campaign (US),1195648107,iOS,banner,4,http://partnername.net/banner4.jpg,423573,15429,454,317.8 2018-01-02,Fresh Air iOS Campaign (US),1195648107,iOS,interstitial,2,http://partnername.net/interstitials2.jpg,1425602,69436,2771,6096.2

Request:

GET

https://api.partnername.net/api/v2.0/reporting/4ru34ur3u4u5i3pteqrt?start_date=2018-01-01&end_dat e=2018-04-01 &format=JSON

The response is in JSON.

[ { "date": "2018-01-01","campaign_name": "Fresh Air iOS Campaign (US)","site_public_id": 1195648107,"os": iOS,"creative_name": "interstitial ","creative_id": 3,"creative_url": http://partnername.net/interstitials4.jpg"impressions": 292088,"clicks": 11244,"installs": 238,"cost": "166.6" }, { "date": "2018-01-01","campaign_name": "Fresh Air iOS Campaign (US)","site_public_id": 1195648107,"os": iOS,"creative_name": "banner ","creative_id": 2,"creative_url": http://partnername.net/banner2.jpg"impressions": 16444743,"clicks": 86716,"installs": 4366,"cost": "3056.2" }, { "date": "2018-01-01","campaign_name": "Fresh Air iOS Campaign (US)","site_public_id": 1195648107,"os": iOS,"creative_name": "banner ","creative_id": 1,"creative_url": http://partnername.net/banner1.jpg"impressions": 802797,"clicks": 40263,"installs": 1800,"cost": "3960.0" }, { "date": "2018-01-01","campaign_name": "Fresh Air iOS Campaign (US)","site_public_id": 1195648107,"os": iOS,"creative_name": "banner ","creative_id": 4,"creative_url": http://partnername.net/banner4.jpg"impressions": 398590,"clicks": 17107,"installs": 763,"cost": "2479.75" }, { "date": "2018-01-01","campaign_name": "Fresh Air iOS Campaign (US)","site_public_id": 1195648107,"os": iOS,"creative_name": "interstitial ","creative_id": 2,"creative_url": http://partnername.net/interstitials2.jpg"impressions": 423573,"clicks": 15429,"installs": 454,"cost": "317.8" }]

Postbacks and Postback Macros

Postbacks are automatic notifications sent by Singular to ad networks through a specific URL selected by the network. For example, whenever Singular registers a successful install resulting from an ad campaign, we alert the ad network with a postback.

Singular supports the following macros in postbacks:

Application Macros

Macro

Value Description

{APP_NAME}

Display Name of the application

{LONGNAME}

Long name (bundle ID) of application

Campaign Macros

Macro

Value Description

{CID}

Campaign Name as specified in Attribution Tracking Tags

{CLID}

Singular assigned click ID (string)

{cl?Network Name}

Network click ID (string) which is passed by the network through Singular's tracking link's cl parameter. Network Name must be replaced with the name by which it is integrated with Singular

{pcrid?Network Name}

Creative ID - Available only if provided in the click.

{pcrn?Network Name}

Creative Name - Available only if provided in the click.

{pshid?Network Name}

Hashed or anonymized ID for the publishing appfor the click(string). Available if passed with the click.

{psid?Network Name}

Source site or application ID for the click(string). Available if passed with the click.

{psn?Network Name}

Source site or application name for the click(string). Available if passed with the click.

{NETWORK=Network Name}

Will return '1' if the attributed network equals to specified Network Name in the macro, '0' if not.

{IS_RE_ENG}

Will return '1' if attributed to a re-engagement campaign, '0' if not.

{IS_VIEWTHROUGH}

Will return '1' if attributed due to an impression link, '0' if not.

Device Related Macros

Macro

Value Description

{TOUCHPOINT_IP}

IP of the device at the time of the attributed touchpoint

{ATTRIBUTION_IP}

IP of the device at the time of the attribution, install or re-engagement

{EVENT_IP}

IP of the device at the time of the executed event

{OS_VERSION}

OS version of the device at the time of the clicked ad

{APP_VERSION}

App version of the device at the time of the install/event

{IDFA}

Unhashed iOS advertising identifier of the device

{IFA1}

SHA-1 of iOS advertising identifier of the device

{IFA5}

MD5 of iOS advertising identifier of the device

{IDFV}

Unhashed iOS identifier for the vendor

{ANDI}

Unhashed Android ID - this identifier is available if the advertising identifier (AIFA) is not available on the device. As this identifier is not always available, we recommend using {AIFA}, or {COALESCE|{AIFA},{ANDI}} to ensure a value is always passed.

{AND1}

SHA1 of Android ID

{AIFA}

unhashed Android advertising identifier of the device

{AIF1}

SHA-1 of Android advertising identifier of the device

{AIF5}

MD5 of Android advertising identifier of the device

{COALESCE}

Pass one ID or the other. Example: {COALESCE|{AIFA},{ANDI}} will let you pass AIFA or ANDI (if AIFA is not available)

{PLATFORM}

iOS or Android

{TOUCHPOINT_COUNTRY}

Country location of the device at the time of the attributed touchpoint

{ATTRIBUTION_COUNTRY}

Country location of the device at the time of the attribution, install or re-engagement

{EVENT_COUNTRY}

Country location of the device when the event occurred

{TOUCHPOINT_CITY}

City location of the device at the time of the attributed touchpoint

{ATTRIBUTION_CITY}

City location of the device at the time of the attribution, install or re-engagement

{EVENT_CITY}

City location of the device when the event occurred

{TOUCHPOINT_STATE}

State/province location of the device at the time of the attributed touchpoint

{ATTRIBUTION_STATE}

State/province location of the device at the time of the attribution, install or re-engagement

{EVENT_STATE}

State/province location of the device when the event occurred

{USERID|user.key} {CUSTOM_USERID|user.key}

Custom user ID. Replace "user.key" with the key of the custom user ID key-value pair. For example, where the key-value is balloonjumpID=username, the macro should be {USERID|user.balloonjumpID}. This will be replaced with 'username'.

{DNT}

Do not track flag is set active a 1 will be returned, all other conditions will return 0

{NODNT}

Do not track flag is set active a 0 will be returned, all other conditions will return 1

{DEVICE_MODEL}

Device model

{DEVICE_BRAND}

Device Brand

{MATCH_TYPE}

Indicates whether and attribution is Organic (null value), deterministic (device id matching or install referrer) or with fingerprinting methodology

{ATTRIBUTION_WINDOW}

The window, in hours, used to attribute the install or re-engagement

{INSTALLER_SOURCE}

Android only - Package name of the source that caused the install. E.g. 'com.android.vending' if the install was from the Google Play store.

{APPSTORE_FLAG}

Android only - 0, 1 or NULL depending on the installer source. Value is NULL if the data is unavailable.

Event Macros

Macro

Value Description

{AMOUNT}

Revenue event postbacks only. The transaction amount in the transaction currency.For rejected revenue events, this will become 0 - see IAP_RECEIVED_REVENUE for the original event name.

{CURRENCY}

Revenue event postbacks only. The three-letter ISO 4217 currency code for the transaction

{EVTNAME}

Name of the event. For rejected revenue events, this will become __iapinvalid__ - see IAP_RECEIVED_EVENT_NAME for the original event name.

{EVTATTR: Attribute_Name}

Value from the specified attribute. For example, if you have an event named 'Checkout' with an attribute 'Number of Items', then {EVTATTR: Number of Items} would return the number of items from the 'Checkout' event.

{IAP_RECEIVED_EVENT_NAME}

For revenue events, the original event name. If the event is valid, this would be the same as EVTNAME.

{IAP_RECEIVED_REVENUE}

For revenue events, the original purchase amount. If the event is valid, this would be the same as AMOUNT.

{IAP_RECEIPT_RECEIVED}

For Revenue events, Returns '1' if a purchase receipt was included, '0' otherwise.

{IAP_RECEIPT_VALID}

For Revenue events, Returns '1' if a purchase was deemed valid, '0' otherwise.

{IS_FIRST_EVENT}

Returns '1' for the first occurrence of an event (revenue or custom), '0' for every subsequent event from the same device ID.

Facebook Macros

Macro

Value Description

{FB_C_ID}

Numeric Facebook Campaign ID. Subject to restrictions based on Facebook's terms of service.

{FB_C_NAME}

Facebook Campaign name. Subject to restrictions based on Facebook's terms of service.

{FB_AS_ID}

Numeric Facebook Ad Set ID. Subject to restrictions based on Facebook's terms of service.

{FB_AS_NAME}

Facebook Ad Set name. Subject to restrictions based on Facebook's terms of service.

{FB_A_ID}

Numeric Facebook Ad ID. Subject to restrictions based on Facebook's terms of service.

{FB_A_NAME}

Facebook Ad name. Subject to restrictions based on Facebook's terms of service.

Twitter Macros

Macro

Value Description

{TWTR_C_NAME}

Twitter Campaign Name. Subject to restrictions based on Twitter's terms of service.

{TWTR_C_ID}

Twitter alphanumeric Campaign ID. Subject to restrictions based on Twitter's terms of service.

{TWTR_G_ID}

Twitter alphanumeric Line Item ID. Subject to restrictions based on Twitter's terms of service.

{tweet_id}

Tweet ID - Applicable to organic twitter installs only. singular suggests the following convention for capturing the Tweet ID for Twitter associated installs: your_parameter={CREATIVE}{tweet_id} This will capture the Tweet ID value for installs attributed to Twitter Campaigns and organic Twitter installs.

Time Macros

Macro

Value Description

{DATE}

Install or event date (string formatted as "YYYYMMDD") in GMT timezone

{TIME}

Install or event timestamp (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone

{UTC}

Install or event timestamp in UNIX format in seconds

{UTCM}

Install or event timestamp in UNIX format in milliseconds

{CLICK_UTC}

Click timestamp in UNIX format in seconds

{CLICK_UTCM}

Click timestamp in UNIX format in milliseconds

{CLICK_TIME}

Click timestamp (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone

{CLICK_DATE}

Click timestamp (string formatted as "YYYYMMDD") in GMT timezone

{INSTALL_UTC}

Install timestamp of latest attribution in UNIX format in seconds (including reengagements)

{INSTALL_UTCM}

Install timestamp of latest attribution in UNIX format in milliseconds (including reengagements)

{INSTALL_TIME}

Install timestamp of latest attribution (string formatted as "YYYY-MM-DD_HH:MM:SS") in GMT timezone (including reengagements)

{INSTALL_DATE}

Install timestamp of latest attribution(string formatted as "YYYYMMDD") in GMT timezone (including reengagements)

{STRFTIME|<constructing values>,ts (optional),round (optional)}

Constructible timestamp. The timestamp can be constructed using the following defined values and any additional desired characters:

%d - Day of month as a zero-padded number (01, 02,...,31)

%m - Month as a zero-padded number (01, 02,...,12)

%Y - Year with four digits (2014)

%H - Hour in 24-hour format

%I - Hour in 12-hour format (the letter "i" is in caps)

%M - Minute as a zero-padded number (00, 01,...,59)

%S - Second as a zero-padded number (00, 01,...,59)

For example, {STRFTIME|%Y-%m-%dT%H:%M:%S} would populate like so: 2014-08-22T10:06:52 "ts" is an optional UNIX timestamp which will be used for the formatting; if no "ts" is specified, the current time is used. Supported "ts" values are {CLICK_UTC}, {INSTALL_UTC}, and {UTC}. For example, {STRFTIME|%Y-%m-%dT%H:%M:%S,{UTC}} "round" is an optional modified which will truncate/round to one of the following: year, month, day, hour, or minute For example if {CLICK_UTC} is 1435627795: {STRFTIME|%s,{CLICK_UTC},month} -> 1433116800 {STRFTIME|%s,{CLICK_UTC},day} -> 1435622400 {STRFTIME|%s,{CLICK_UTC},hour} -> 1435626000 {STRFTIME|%s,{CLICK_UTC},minute} -> 1435627740

Other Macros

Macro

Value Description

{RAND}

Random 10 character integer

{JSON}

Used to convert the request from GET to POST with a JSON payload. Everything to the left of that macro is evaluated normally, but the part to the right is removed from the URL, converted into a JSON dictionary equivalent to the query string parameters, and we perform an HTTP POST to the URL left of the {JSON} macro.

{POST}

Similar to the {JSON} macro, except the payload is sent using the older application/x-www-form-urlencoded encoding.

{HTTP_HEADER|k,v}

Add a single key/value pair to the HTTP header using this macro. Add additional key/value pairs by adding additional instances of the macro, e.g. {HTTP_HEADER|SampleKey1,SampleValue1}{HTTP_HEADER|SampleKey2,SampleValue1}. This macro will be used to populate the header and will be completely removed from the URL when sent, so do not add any additional characters such as '&' or '?' when adding this macro to the URL, e.g. https://theURL.com/endpoint?{HTTP_HEADER|SampleKey1,SampleValue1}singular_cl={CLID}&andi={ANDI}{HTTP_HEADER|SampleKey2,SampleValue2}

Macro Modifiers

Macro

Value Description

{SHA1|{Macro}}

Modifier will encode the value as SHA-1. For example, if the {CLID} macro returned '1000', {SHA-1|{CLID}} would return 'fb2f85c88567f3c8ce9b799c7c54642d0c7b41f6'.

{MD5|{Macro}}

Modifier will encode the value as MD5. For example, if the {CLID} macro returned 'ABCD', {MD5|{CLID}} would return 'cb08ca4a7bb5f9683c19133a84872ca7'.

{BASE64|{Macro}}

Modifier will encode the value as standard Base64. For example, if the {CLID} macro returned 'ABCD', {BASE64|{CLID}} would return 'QUJDRA=='. (The returned value will be HTTP encoded in the URL)

{BASE64U|{Macro}}

Modifier will encode the value as url-safe Base64. For example, if the {CLID} macro returned 'ABCD', {BASE64U|{CLID}} would return 'QUJDRA=='. (The returned value will be HTTP encoded in the URL)

{HMACSHA1|{Macro},key}

Modifier will encode the value as HMAC SHA-1 using the provided key. For example, if the {CLID} macro returned 'ABCD', {HMACSHA1|{CLID},sample} would return 'f5143f3dda1b120ac280a82b2cae0ff60dc342b5'.

{HMACMD5|{Macro},key}

Modifier will encode the value as HMAC MD5 using the provided key. For example, if the {CLID} macro returned 'ABCD', {HMACMD5|{CLID},sample} would return '43d752ccec4044f90a66a7d15762075e'.

{UPPER|{Macro}}

Modifier will return the provided value in upper case characters. For example, if the {CLID} macro returned 'abcd', {UPPER|{CLID}} would return 'ABCD'.

{LOWER|{Macro}}

Modifier will return the provided value in lower case characters. For example, if the {CLID} macro returned 'ABCD', {LOWER|{CLID}} would return 'abcd'.

{MULTIPLY|{Macro},multiple}

Modifier will multiply the number by the value returned by the macro to the nearest whole number. To convert the value of a product purchase in floating point to micro it requires multiplying the {AMOUNT} macro 1e6 (1000000). For example, a $5250.23 purchase would become 5250230000 when formatted as {MULTIPLY|5240.23,1000000}.

Passthrough Parameters

In the process of creating an integration with Singular, ad networks can ask to receive additional pieces of information in their attribution postbacks. These are called passthrough parameters and they can include any parameter that is not already used or included in the Singular tracking link. For example, an ad network can ask to receive the internal advertiser ID, e.g. aid=115873.

Advertisers can also take advantage of passthrough parameters to add information to the tracking link that they wish to receive in postbacks to their own servers.

Learn what postbacks Singular can send to partners in case an attribution decision is changed by Singular's Fraud Prevention Suite. For general information about the Suite, see Singular Fraud Prevention.

If you are a Singular customer, read the Fraud Postbacks guide for customers instead. It contains more information that you need to know.

In this article:

What are Fraud Postbacks?

When do Singular Partners Receive Fraud Postbacks?

What Information Do Fraud Postbacks Include?

What Do I Need to Do to Receive Postbacks?

Limitations

What are Fraud Postbacks?

Fraud postbacks are automatic real-time notifications sent by Singular's attribution solution when the attribution of a certain conversion is affected by a decision made by Singular's Fraud Prevention Suite.

Fraud postbacks are available to every customer of Singular's Fraud Prevention Suite. The customer can enable or disable fraud postbacks per app per ad network.

To learn more about Singular's anti-fraud tools, see Singular Fraud Prevention.

When do Singular Partners Receive Fraud Postbacks?

Partners can receive fraud postbacks in case of a rejection decision - meaning, when an app install would have been attributed to a certain touchpoint (click or view), but the touchpoint is rejected by Singular's Fraud Prevention Suite.

Note: As mentioned above, Singular only sends fraud postbacks to partners if the customer has enabled this functionality for the specific app and partner.

What Information Do Fraud Postbacks Include?

Fraud postbacks include the reason why the touchpoint was rejected.

The rejection reason can be either one of Singular's built-in Fraud Protection Methods (see details in the table below), or a custom rule defined by the customer.

Rejection Reason

Meaning

"Android Install Validation"

Android Install Validation is a proprietary, deterministic method developed by Singular to protect customers from fake install attacks on Android devices. If an attribution fails Android Install Validation, it means Singular does not think the install was really carried out by a real Google Play user.

"iOS Install Receipt Validation"

Singular evaluated the install using the receipt that Apple provides for each app installed on an iOS device through iTunes, and found that the install was not carried out by a real user on a real device.

"Android Click Injection"

The touchpoint (impression or click) was found to be part of a click injection attack.

"Android Organic Poaching"

The install was found to be defined as organic by the Google Play store (not associated with any ad click), and therefore the click associated with the install is identified as an organic poaching attempt.

"Time-to-Install (TTI) Outliers"

This attribution was rejected on the basis of the Time-to-Install (TTI) - the time between the click and the install - which is one way to identify a "click injection" attack.

"Geo-Bleed"

Singular detected a distance between the click location and the install location that was impossible for a real end-user to travel in the time that passed between the click and the install.

"Hyper-Engagement"

Singular detected an influx of clicks from the same source, which is an identifier of click spamming or click injection attacks.

"Blacklisted IP"

Singular detected activity from a known suspicious IP range.

"User-Defined Rule"

The touchpoint was rejected based on a custom rule defined by the customer.

What Do I Need to Do to Receive Postbacks?

If you want to start receiving fraud postbacks from Singular, please contact the Singular support team and give us the following details:

An API endpoint to post postbacks to (it can be the same endpoint that you use to receive install postbacks);

The parameter in which to place the rejection reason.

Limitations

1. Only One Rejection Postback per Install

Rejection postbacks are only sent for one touchpoint per install - the touchpoint closest to the install. The Fraud Prevention Suite may reject other touchpoints associated with the same install, but no postbacks will be sent for those.

Example:

In this example, Singular found two clicks associated with the install. The Fraud Prevention Suite has examined the two clicks and has rejected them both.

Final attribution decision: The install is marked as organic.

Fraud postbacks: Singular sends a rejection postback to Network B for Click 2.

2. No Fraud Postbacks if the Fraud Decision Didnt Affect the Attribution

Rejection postbacks are not sent for touchpoints other than the one the install would have been attributed to.

If the touchpoint that is closest to the install is judged to be valid (or marked as suspicious but not rejected), and therefore the install is attributed to it, earlier touchpoints are still evaluated by the fraud prevention system. However, regardless of the result of the evaluation, no rejection postbacks will be sent for any of those earlier touchpoints.

Example:

In this example, Singular found two clicks associated with the install. The Fraud Prevention Suite has examined the two clicks with the following results:

Click 2 (Network B) - the touchpoint closest to the install - valid

Click 1 (Network A) - rejected

Final attribution decision: The install is attributed to Network B for Click 2.

Fraud postbacks: No fraud postbacks are sent, because the rejection of Click 1 didn't affect the attribution decision.

Background

To maximize granularity, Singular has introduced a variety of parameters to report the myriad of fields integrated ad networks support. These parameters, when properly populated by the ad network, allow us to join the device-level dataset represented by clicks, impressions and events with the aggregated dataset we are pulling from ad networks for ad spend, targeting and other upper funnel metrics.

This article covers all currently supported tracking link parameters that represent ad network objects (e.g. Campaign), and how they are represented in Singular's UI and API.

Introduction to Granularity Parameters

Granularity Parameters are tracking link parameters that report on the variety of objects ad networks can track clicks and impressions by. Common objects are Campaigns, Creatives and Publishers (which is in Singular is considered as the publishing app), but there's a lot more!

Unfortunately, there are also network-specific objects such as Zones, Sites and many others. When handling granularity for our ad network data as well as attribution data, we have created a common scheme to try and fit all of these fields into, without concatenating any parameters which would then complicate data joins.

The Singular approach for creating tracking links is to always ensure we are utilizing all parameters available in order to maximize granularity, and when used correctly -- these would get populated by the ad network and propagate into tracking links, attribution data and app events. These fields would then be available both in device-level exports as well as

Hierarchy

Name in Singular UI

Meaning

Tracking Link Parameter

Device

Platform

Device Platform (Android/iOS)

p

IP

IP of the device at the time of the click

ip

Click ID

Click or Transaction ID

cl

OS Version

OS version of device

ve

IDFA

Unhashed / Raw iOS Advertising ID

idfa

IFA-1

SHA-1 of iOS Advertising ID

ifa1

IFA-5

MD5 of iOS Advertising ID

ifa5

AIFA

Unhashed / Raw Android Advertising ID

aifa

AIF-1

SHA-1 of Android Advertising ID

aif1

AIF-5

MD5 of Android Advertising ID

aif5

ANDI

Unhashed / Raw Android ID

andi

AND1

SHA-1 of Android Advertising ID

and1

AND5

MD5 of Android ID

and5

Campaign

Campaign Name

This is the campaign name the network reported

pcn

Campaign ID

This is the campaign ID the network reported

pcid

Sub Campaign

Sub Campaign Name

Name of the object sitting under campaigns where applicable (e.g. Ad Set Name in Facebook)

pscn

Sub Campaign ID

ID of the object sitting under campaigns where applicable (e.g. Ad Set ID in Facebook)

pscid

Creative

Creative Name

Name of ad / creative

pcrn

Creative ID

ID of ad / creative

pcrid

Publisher

Publisher ID

Hashed or anonymized ID for the publishing app

pshid

Publisher Site Name

Name of publishing app for supporting networks

psn

Publisher Site ID

Store ID of publishing app for supporting networks

psid

Sub Publisher

Sub Publisher Name

Name of the site, or placement, within the publishing app

pssn

Sub Publisher ID

ID of the site, or placement, within the publishing app

pssid

Keyword

Keyword

Keyword for AdWords and Apple Search Ads

kw

Affiliate

Affiliate Name

Affiliate name for affiliate networks who report it

paffn

Affiliate ID

Affiliate ID for affiliate networks who report it

paffid

Singular will track "auto-generated" events if an SDK or S2S integration is enabled. These auto-generated events may appear in user level event exports or certain partner postbacks (if the partner is receiving the auto-generated event name), or in Internal BI postbacks. The table below lists a few of these common auto-generated events, what the auto-generated event name is,and how they are triggered and tracked

Event

Event Name

When it is Tracked

Install

__START__

Automatically tracked when sessions are being sent via the SDK or S2S integration.

Session

__SESSION__

Automatically tracked when sessions are being sent via the SDK or S2S integration.

SDK Revenue

__iap__

Tracked if revenue is reported via the "revenue" method in the Singular iOS or Android SDK

Any Revenue

__REVENUE__

Tracked if any revenue is tracked. For example, the __REVENUE__ event will trigger whenever revenue from the SDK via __iap__ is triggered, and also triggered if you are reporting revenue via S2S with an event name like "purchase". It not recommended to use this if __iap__ or other S2S revenue postbacks are configured for the same postback endpoint as duplicate revenue might be reported.

Uninstall

__UNINSTALL__

Automatically tracked if uninstall is enabled for your iOS or Android app, and at least one uninstall has been tracked. If an uninstall is detected for a device, it is triggered once a day.

Reinstall

__REINSTALL__

Automatically tracked if uninstall is enabled via the SDK/S2S. If an __UNINSTALL__ for a device is tracked, and then a subsequent __SESSION__ is triggered, the __REINSTALL__ event is also triggered

To track app installs coming from Apple Search Ads campaigns, integrate Singular's iOS SDK (version 7.3 and greater), and make sure the iAd andAdSupport frameworks are included in your iOS application build.

The Singular SDK utilizes the Apple Attribution API in the framework to retrieve advertising information for any ad click as detected by Apple.

Installs from Apple Search Ads are fed through Singular last click attribution methodology.

Reporting on Apple Search Ads Installs

Singular reports use the values as named in your Apple Search Ads campaigns. You can also use special keywords to provide even more insights into how your users are acquired.

Apple Search Ad values are mapped to Singular reporting dimensions as follows:

Singular Value

Apple Search Ads Value

Example

Tracker Campaign Name

Campaign Name

MyCampaign

Tracker Campaign ID

Campaign ID

12345678

Tracker AdGroup Name

AdGroup Name

MyAdGroup

Tracker AdGroup ID

AdGroup ID

98123747

Source

Apple Search Ads

Apple Search Ads

Keyword

Keyword

bubbles

When you run a report in Singular, Apple Search Ads will also match the SDK data with the spend data provided by Apple Search Ads API, including:

Spend by Campaign

Spend by Keyword

To start pulling marketing data from Apple Search Ads, add a data connector for Apple Search Ads in the Data Connectors page. See the Data Connectors FAQ for more information.

Note that tracker install discrepancies are expected as Apple's definition of an install is a successful 'download', where as Singular's definition is counted only when the user opens the app for the first time, after the download has finished.

In this article:

Submitting a Support Request

Tracking Your Request

Singular's customer service and customer success teams are here to help you with everything you need to make full use of Singular.

Submitting a Support Request

To open a support request form, you can:

Go to the submission page (make sure you are logged into your Singular account).

Or, from within the platform, select Help > Submit a Ticket.

My activities

What to Include in the Support Request?

When you submit a request, please be as detailed as possible. The more information you provide, the faster we'll be able to handle your request.

First, let us know whether you have a question, a problem, or a request.

Be specific in your description, especially if you are experiencing an issue: who is the partner, what's the date range, app name, and anything else that can help pinpoint the problem.

Add screenshots and links to reports when you can.

If you are a partner/agency, make sure you include the customer's name.

Let us know the impact an issue has on your business. Do you have a big launch and need the issue fixed beforehand? What percentage of your daily operations is affected?

If you're not sure whether a piece of information is relevant, it's always best to share it with us. We'll look at it and see if it's connected.

Contacting Support vs. Contacting Your Customer Success Manager

As a rule, you should contact Singular's support team for your operational needs regarding the Singular platform. Feel free to CC your CSM when you do so to keep them informed.

Your CSM's job is to help you make better use of the platform, for example by training new team members and reviewing new features with you.

Tracking Your Request

When Singular replies to your support request, you will receive an email. You can reply to the email directly or go to the link provided in the email and enter your reply there. If needed, we're always happy to schedule a call.

To review your communication with Singular (including solved requests and requests in progress), go to the page. You'll also be able to see if we're waiting for you to respond before we can continue.

Note that the My Activities page is only available to logged-in users.

Google App campaigns (formerly Universal App campaigns) help you promote your mobile app across all the Google networks. With a few steps, you can enable Singular to track the performance of different types of app promotion campaigns, across across Google Search, YouTube, and over three million sites and apps in the Google network. Both click-through and view-through attributions can be tracked with Google Ads.

Note: Google Ads' view-through attributions are based on MRC definition of viewability and is only available for Youtube and Display networks.

The below tables summarize these different Google Ads networks, options for how you want to promote your app in these networks, and how to enable Singular to track them. To review how to enable Singular to track these campaigns for you, skip down to the set-up.

Google Networks

Network

Description

Google Search

These are text ads appearing on Google Search, the Google Search App, and Google Play.

Google Display

These are image ads in a mobile applications and mobile web browsers that can link to your mobile website, mobile app, or app store.

Google Ads for Video (Youtube)

These are video or text ads appearing in the Google YouTube iOS or Android apps.

Google Ads Campaign Types

Type

Description

Singular Tracking

App Campaigns

App Campaigns is a one-stop-shop to promote your mobile app on all available networks. These ads are auto-generated based on the creative text you enter. Available for both iOS and Android apps.

Installs

App Campaigns for Engagement

App campaigns for engagement helps your current app users take specific in-app actions with the goal of improving user retention and long-term revenue.

Re-engagements

How Attribution Tracking with Google Works

Tracking your Google Ads campaigns in Singular is performed via a self-attributing server-to-server integration. This integration allows Singular to track all installs and re-engagements driven from any of your Google Ads campaigns. Both click-through and view-through attributions are supported and available as a conversion type breakdown in reporting. The integration utilizes a Link ID which is generated in Google Ads and unique to each app. Once your Link ID has been configured in Singular, Singular will start sending all installs, sessions, and configured in-app conversion events to Google. Using the attributed click information returned from Google, Singular is able to perform last-click attribution and report using the same granular campaign information as seen in your Google Ads dashboard.

To continue on to setting up your Google Ads integration in Singular, continue down to Integration Steps below.

Integration Steps

1. Integrate The Singular SDK

In order for Google Ads attributions to be tracked, the Singular SDK must be present. If your application supports deep links, it is also required that deep link URI support be implemented to ensure all Google Ads campaigns can be tracked in Singular. Review our iOS and Android SDK guides to ensure sessions and deep links are handled correctly. If you are utilizing the S2S integration with the Singular server-to-server integration, reach out to your Singular customer success team for further details.

2. Get Your Apps Link ID

Generate a Link ID in your Google Ads account as explained in Google's instructions. There are two options to generate a Link ID to use with Singular.

The recommendation is to use cross-account conversion tracking with an MCC account

My Client Center, commonly known as an MCC, is an umbrella account used to manage multiple Google Ads accounts without having to constantly log in and out of each individual Google Ads account. The MCC features a linking system which allows regular accounts to be connected to this single umbrella account without login details ever having to be exchanged.

If cross-account conversion tracking via MCC accounts isn't possible, you can also share a link ID with another Google ads account.

3. Set Up the Integration in Singular

Search for "AdWords" in Partner Configurations. Select your desired "App," "Site," and provide your App's Link ID.

Default settings:

View-through Tracking: Enabled by default.

Re-engagement Tracking: Enabled by default and mandatory if you are running re-engagement campaigns with Google.

Click-through attribution window: You can customize this setting.

Any available post-session app events are automatically included by default, with the option to exclude. Under "Google app event type" you will find a list of Google's predefined events. Map your events to the equivalent Google event, or leave the event as "custom"

Note: Sessions (to enable re-engagement) are automatically sent to Google. No additional configuration is required. This is required per the Google Ads integration.

document

4. Import Conversions and Configure your Google Ads Campaigns

To begin tracking conversions, you first need to configure the events on Google's platform. This is what Google refers to as "importing events." This enables Google to start receiving post-install events. For instructions on importing conversion events, see Google's instructions. For install tracking, you have to import the "first open" event in Google Ads. For re-engagement campaigns, make sure that you import "session_start".

The events show up in Google Ads after at least one conversion event occurred since setting up the configuration in Singular (not just events that are attributed to Google Ads).

For live apps with thousands of active users, this usually happens within a few minutes, but if you are testing a new app without any active users, you have to trigger the events yourself.

Then, make sure that the conversion is enabled - this might have to be done through the MCC account if you are utilizing cross-account conversions.

Next, you can configure and start your Google Ads campaigns. Follow Google's instructions to learn more about your options and how to configure them.

5. Verification - Singular Reporting for AdWords

Once an attribution is tracked, your Google Ads campaigns will appear in your Singular Reporting interface. Below is a sample of the reporting, filtered for AdWords.

Note that "Conversions" in Google Ads refer to both Installs and Re-Engagements in Singular.

In addition, there are inherent discrepancies between Google Ads and all 3rd parties, as outlined in the following Google Ads .

You can easily integrate the Singular SDK within your app using our SDK documentation.

Find all the tools for building the integration under Settings > SDK Keys.

SDK Key

This key is necessary for the Singular servers to identify your account.

Apple Search Ads API

Developer Account

Use a developer account during the development and QA process in order to keep your main account data clean. You can find your Developer Account credentials in the SDK Keys page, as in the following example.

The developer account contains a separate SDK key that can be used in development versions of your app.

Important: Remember to switch to the main SDK Key before deploying to the App Store.

Available SDKs

We currently provide 4 ways to integrate with Singular:

Android SDK

iOS SDK

Unity SDK

Server to Server integration

SDK Console

The SDK Console displays calls for session and event data sent by the Singular SDK or direct use of the Singular Server to Server API. It is a tool for application developers to verify if their instrumented events and sessions are being received by the Singular platform.

Adding Devices

To add a device:

Select the Platform and Keyspace of the device that you want to test

Insert the identifier and click "Add"

Once the device is added, the event logs will start collecting data. You can view event logs for multiple devices at once by selecting the Show/Hide Button:

Note: you can add up to 20 devices at once.

Deleting Devices and Clearing Attribution

To delete a device, hover over the Device ID and select the Delete button. This will clear all event logs from the screen, but will not clear the attribution.

To clear a device's attribution, select the Forget button. This will reset the attribution for a specific device so you can retest with the same device.

Using the Console

Once a device is registered, events trigged in the app via the SDK will appear in the console . You can drill down on a specific line item to view more details:

Automatically Tracked Events

Aside from your explicitly tracked sessions and events, there are some events that are tracked automatically by the SDK and may become useful in debugging/understanding the data in some scenarios:

SDK Event Name

Description

__installReferrer__

Android Only - This event contains the payload of the Android install referrer (when available). If the Android install referrer is implemented, this event is automatically sent shortly after the Android SDK initialization. This event is used as part of the Singular attribution process.

__iAd_Attribution__

iOS Only - This event contains the payload of the response (when available). This event is sent shortly after the iOS SDK initialization. This event is used as part of the Singular attribution process.

Partners who use the Everflow platform can find the relevant macros and their mapping to the Singular parameters in the list below:

Parameter

Hierarchy

Meaning

Everflow macro

pcn

Campaign

Campaign Name

{offer_name}

pcid

Campaign

Campaign ID

{offer_id}

pscn

Sub Campaign

Sub Campaign Name

{sub2}

pscid

Sub Campaign

Sub Campaign ID

{sub1}

pcrn

Creative

Creative Name

{creative_name}

pcrid

Creative

Creative ID

{creative_id}

pshid

Publisher

Hashed Publisher (app) ID

{sub3}

paffid

Affiliate

Affiliate ID

{affiliate_id}

idfa

Device

Unhashed/raw iOS Advertising ID (recommended)

{idfa}

idfa1

Device

SHA-1 of iOS Advertising ID

{idfa_sha1}

idfa5

Device

MD5 of iOS Advertising ID

{idfa_md5}

aifa

Device

Unhashed/raw Android Advertising ID (recommended)

{android_id}

and1

Device

SHA-1 of Android ID

{android_id_sha1}

and5

Device

MD5 of Android ID

{android_id_md5}

ip

Device

IP of the device at the time of the click

{user_ip}

ve

Device

OS version of device (E.g. 8.0.1 and not 8.0)

{device_os_version}

p

Device

Device platform (required for s2s integrations only)

{device_platform}

cl

Click

Click or Transaction ID

{transaction_id}

In this article:

Fraud Protection Methods

User-Defined Rules

The Fraud Detection Process

Fraud Reporting

Fraud Postbacks

Singulars Fraud Prevention Engine actively protects your marketing efforts using a mixture of out-of-the-box detection methods and custom user-defined rules to prevent attribution fraud.

The Fraud Prevention Engine evaluates installs before finalizing the attribution or reporting it to the partner, thus preventing excessive billing for CPI/CPA campaigns.

Fraud Protection Methods

Singular has conducted extensive research into attribution fraud to detect and implement the most useful and actionable fraud prevention methods in the market. The methods are fine-tuned based on the collective information from Singulars clients to achieve the best results while minimizing false positives.

The customer can activate or deactivate each method separately. When activating a method, the customer can choose whether touchpoints that trigger this method should be Rejected (declared as unsuitable for attribution) or just marked as Suspicious for later follow-up.

For more information about activating fraud protection methods, see Configuring Fraud Settings.

Fake Installs Protection Methods

While other types of attribution fraud rely on stealing the credit for legitimate app installs, install fraud is based on the creation of fake installs and fake users for the purpose of getting the installs attributed.

NEW: Android Install Validation

To tackle install fraud on Android, Singular has developed Android Install Validation - a proprietary, deterministic method of evaluating an install and making sure it is legitimate. Android Install Validation detects and prevents all known forms of fake install attacks at a significantly higher level of accuracy than any tools developed previously.

See Advanced Android Fraud Protection for more information.

iOS Install Receipt Validation

Apple provides a receipt for each app installed on an iOS device through iTunes. The receipt can be used to verify that the app has been installed by a real user on a real device. Receipt verification is a multi-step process:

Making sure that a receipt exists.

Verifying the authenticity of the receipt by checking Apples digital signature.

Validating the receipt by matching the receipts details to the current installation (for example comparing the apps longname).

Ensuring that the receipt hasnt been used for another install (so that fraudsters wouldnt re-use the same receipt on multiple installations/devices).

Note: Singular performs receipt validation only on devices with iOS 7.0 or higher and only when the app includes a Singular SDK of version 8.2 or higher.

Attribution Manipulation Protection Methods

NEW: Android Click Injection Protection

In click injection, the fraudster detects an app install by a real user and creates a fake click (or impression) in order to hijack the install attribution.

To protect against click injection, Singulars new detection method uses Google Play Referrer values and timestamps to identify impressions and clicks that occur after users were directed to the Play Store or initialized an install.

See Advanced Android Fraud Protection for more information.

New: Android Organic Poaching Protection

In Organic Poaching, a fraudster claims credit for an app install that is, in fact, organic and should not be attributed to any source.

Singulars new protection method detects signals from the Google Play Store that an app install is organic (not associated with any ad clicks). Any clicks associated with this install can then be identified as an organic poaching attempt.

For more information, see Advanced Android Fraud Protection.

Time-to-Install (TTI) Outliers Detection

Click injection attacks involve detecting an installation and firing a fake click. They can often be detected by looking at the Time-to-Install (TTI) - the time between the click and the install. The click is fired right as the app finished installing, so it often results in an abnormally short TTI.

Geo-Bleed Detection

Singular detects a distance between the click location and the install location that was impossible for a real end-user to travel in the time that passed between the click and the install. For example, if an end-user clicks an ad, and two hours later there is an install event from 10,000 km away, this is probably a fraudulent install.

Hyper-Engagement

Attacks such as click spamming and click injections create an influx of clicks from the same source. Singular detects the suspicious activity and can reject clicks coming from the same source.

General Protection Methods

Blacklisted IPs

Singular detects touchpoints coming from known suspicious IP ranges, which include:

Cloud Service Providers and Data Centers

Proxy and IP anonymization services

TOR exit points

High-risk IPs: IPs thats have been spotted doing fraudulent or other abusive activity on the internet.

Singular maintains a regularly updated list of these IP ranges.

User-Defined Rules

In addition to the fraud protection methods developed by Singular, customers can create custom rules to prevent types of fraud that are specific to that customers apps.

For example, a customer may want to reject clicks where the publisher is a certain problematic publisher and the Time to Install (time between click and install) is under a certain number of seconds.

For more information, see Configuring User-Defined Fraud Rules.

The Fraud Detection Process

The fraud detection process comprises the following steps:

1. Logging all touchpoints

Touchpoints include end-user events such as clicks, impressions (view-through), Self-Attributed Network touchpoints (from networks such as Facebook, AdWords, and Twitter), and additional special touchpoints such as Google Play Install Referrer information.

2. Logging the install event

When the app is first opened, an install event is triggered and sent to Singulars servers. Singular logs the install and gathers all matching touchpoints.

3. Evaluating all the attribution candidates

The Fraud Detection Engine assembles a list of all the attribution candidates and evaluates each one based on all the fraud prevention methods and the custom fraud rules.

For example, here is an install with two associated touchpoints:

Fraud Postbacks

In this example, the attribution candidates are:

Network B (for Click 2)

Network A (for Click 1)

Organic

The Fraud Prevention Engine may reject any touchpoint for fraud. It may also reject the organic option - if the install itself is found to be fake. For example, the Engine may reject the organic install option if the install event comes from a blacklisted IP that is associated with bot activity.

Depending on your fraud settings, some touchpoints may not be rejected but only marked as suspicious. These touchpoints are still valid candidates for attribution, but you will be able to see in your reports that they were marked as suspicious, for your further investigation.

4. Making the final attribution decision

Singulars attribution mechanism goes over the attribution options in order of best to worst, and attributes the install to the best option that has not been rejected by the Fraud Prevention Engine.

If all options have been rejected for fraud (including the option of it being an organic install), the install is marked as Untrusted.

5. Updating the reports and sending postbacks

For "Rejected" Decisions:

If the attribution decision was influenced by the Fraud Prevention Engine - meaning, if the best attribution candidate was rejected - Singulars attribution mechanism:

Adds a rejection to the rejection report

Sends a rejection postback (if rejection postbacks have been configured - see see Fraud Postbacks ).

If the Fraud Prevention Engine didnt change the attribution decision, no fraud postback is sent. For example, the Engine might have rejected a lower-priority click. This is not counted as a rejection for the purposes of rejection reports and fraud postbacks.

For "Suspicious" Decisions:

Touchpoints that were marked as "suspicious" by the Fraud Prevention Engine are still valid candidates for attribution. If Singular's attribution mechanism selects one such touchpoint as the final attribution decision, it:

Adds a suspicious install to the suspicious report.

Adds a parameter to the install postback sent to the customer's internal BI (if such postbacks have been configured - see Fraud Postbacks ). The parameter includes the reason for the suspicious decision.

Untrusted installs are also marked as suspicious and will appear in the suspicious report.

Examples

Lets look at some simple cases of attribution decisions affected by fraud evaluation results.

Example 1: Rejected Click

#

Fraud detection process: In this example, the Fraud Prevention Engine went over all the touchpoints and decided to reject Click 2 for fraud.

Attribution logic: The attribution mechanism has to choose between the following attribution candidates:

Network B (for Click 2)

Network A (for Click 1)

Organic

If no fraud evaluation existed, Click 2 would be the best option for attribution, as it is the click closest to the install. However, Click 2 is rejected, so the next-best option is chosen.

Attribution Decision: The install is attributed to Network A (for Click 1).

Reports: Singular adds a rejection for Network B to the rejection reports.

Postbacks: Singular sends Network B a rejection postback.

Example 2: All Clicks are Rejected

#

Fraud detection process: In this example, the Fraud Prevention Engine went over all the touchpoints and rejected both click 1 and click 2 for fraud.

Attribution logic: The attribution mechanism has to choose between the following attribution candidates:

Network B (for Click 2)

Network A (for Click 1)

Organic

Attribution decision: Since all clicks are rejected, the install is marked as Organic.

Reports: Singular adds a rejection for Network B to the rejection reports.

Postbacks: Singular sends Network B a rejection postback.

Example 3: Even the Organic Option is Rejected (Untrusted Install)

#

Fraud detection process: In this example, the Fraud Prevention Engine went over all the touchpoints and rejected both click 1 and click 2 for fraud. The Engine also rejected the install event itself as fake.

Attribution logic: The attribution mechanism has to choose between the following attribution candidates:

Network B (for Click 2)

Network A (for Click 1)

Organic

Attribution decision: Since all clicks are rejected, and the Organic option is rejected as well (because the install event was found to be fake), the install is attributed to Untrusted.

Reports:

Singular adds a rejection for Network B to the rejection reports

Singular adds a suspicious install to the suspicious reports, attributed to Untrusted.

Postbacks: Singular sends Network B a rejection postback.

Fraud Reporting

Singulars fraud reporting tools allow you to track Fraud Prevention Engine decisions and analyze fraudulent activity related to each of your apps.

See Fraud Prevention: Reporting for more information about the available reports and how to use them.

Fraud Postbacks

Singular can send automated postbacks about fraud decisions to the relevant ad network and/or to the customers internal BI platform.

There are two types of fraud postbacks:

Rejection postback: Sent when an install would be attributed to a certain touchpoint, but the touchpoint is rejected by Singulars fraud prevention system.

Notification about a suspicious install: Sent to the customers internal BI systems when an install is attributed to a touchpoint that is marked as suspicious.

See for more information.

Tracking your campaigns with Singular's attribution is a few steps away.

Follow these simple steps to start using the attribution service:

SDK Integration

Application Management

Event Management

Partner Management

Generating Tracking Links

This article describes how to configure attribution settings for Facebook. To learn how to set up Facebook as a data connector, see Pulling Data from Facebook.

With Facebook Mobile App Install Ads, you can launch advertisements on Facebook's Audience Network and target relevant groups of people at the right time and place. Singular is a Facebook Mobile Measurement Partner that allows app publishers to track ad download referrals that come from Facebook.

With Singular, you can track both click-through and view-through performance for your Facebook campaigns. Once a download has been verified by Singular, you can also track subsequent user engagement and monetization of these users in your mobile app.

Singular's Facebook campaign tracking integration also includes Instagram tracking. Once your Facebook tracking integration is set up with the below steps, Instagram conversions will be tracked within Singular as well.

To set up Facebook attribution tracking for an application:

Prerequisites:

Make sure your app is integrated with Singular via the Singular SDK or a S2S integration. For more information, see iOS integration, Android Integration, S2S Integration. Accept Facebooks Advanced Mobile Measurement Agreement: To agree to Facebook's Advanced Mobile Measurement Agreement, or check your status with this agreement, click here.

Set up Facebook mobile app install ads:

Register the application on Facebook - To run Facebook Mobile App Install Ads the application must be registered with Facebook. Visit the Facebook App Dashboard to set up your application.

Create a Facebook Mobile Install Ad - Singular supports tracking Mobile Install Ads on Facebook's Audience Network. To create your ad, consult the Facebook Mobile App Install Ads tutorial.

Add Facebook App ID to your Singular Account:

Retrieve your Facebook App ID from your Facebook App Dashboard.

Using the Facebook SDK and Singular SDK/S2S in the Same App

Navigate to the Partner Configuration page of your Singular Account.

Search for Facebook in the partner search box:

Confirm you have signed the Facebook Advanced Mobile Measurement agreement in your Facebook Ad Accounts. This allows Singular to share Facebook data with any of your connected BI tools.

Enter your Facebook App ID

Tip: You can add multiple Facebook App IDs by separating them with a with a comma, for example:

View-through tracking is enabled by default but can be disabled if needed by deselecting:

Save the integration.

Note: By saving the Facebook integration configuration here, Singular is automatically tracking installs and sessions to Facebook. This corresponds to the mobile_app_install and fb_mobile_activate_app events. You do not need to configure these events separately in step 5.

Send Event Postbacks to Facebook (Optional): Singular supports sending event notifications to Facebook with all of Facebook's requirements.

First, select enable sending in-app events to Facebook by selecting All.

Next, map your In-app events:

Select the event name on the left field, according to the name used in the SDK, and map the name to one of Facebook predefined conversion events.

Check the Send value checkbox if relevant (for example, revenues). If not checked, only counts of the event will be sent.

See also:

Facebook In-app Event Requirements

Some Facebook in-app events require certain arguments to be passed in order to be processed by Facebook. Please see the below required arguments for Facebook in-app events

Facebook Event Name

Required Argument(s)

Supported Values

AdClick

ad_type

ad_type - "banner","interstitial","rewarded_video","native"

AdImpression

ad_type

ad_type - "banner","interstitial","rewarded_video","native"

For example, if you are sending an SDK event called "Click" and would like to map it to the Facebook Event Name "AdClick", ensure that "ad_type" is being sent in the "Click" event like below:

Android Example:

Singular.event("Click", "ad_type", "banner");

iOS Example:

[Singular eventWithArgs:@"Click", @"ad_type", @"banner", nil];

Tracking Facebook Mobile App Installs in Singular

After completing the steps above to enable Facebook Attribution Tracking, you can see the results of your Facebook's Audience Network campaigns in your Singular Reporting. Each install attributed to a Facebook Mobile App Install Ad will automatically be reported based on the Campaign Name, Ad Set, and Ad Group Name created in Facebook's Platform.

Attributions from ads within Facebook's App will be reported with the Publisher Facebook. Attributions from Instagram will show Instagram as their publisher. Attributions from Partner Mobile Apps on Facebook's Audience Network will show Audience Network as their publisher:

About Click-Through Tracking

As with all click attribution, Facebook click-through attribution refers to the ability to credit an ad campaign for an install if an individual has clicked on an ad prior to that install. When a user clicks an ad, installs the app, and later launches the app, its assumed that the click led to the download, and that installation is attributed to that specific ad. Clickthrough attribution is always given credit for an install if there are clicks that have occurred in the attribution window. If there are no clicks, then view-through tracking is applied.

About View-Through Tracking

View-through refers to the ability to credit an ad campaign for an install even if no one has clicked on an ad. The idea behind view-through is that it makes a causal contribution to driving an install even if the viewer does not click the ad.

Singular is pleased to offer view-through tracking for Facebook. By tracking Facebook view-through as part of your app attribution and measurement, you will be able to make smarter decisions about campaigns, creative executions and more. With Facebook view-through, the last ad impression is credited with an install if there are no ad clicks to which you can attribute that install. View-through is an increasingly becoming an invaluable measurement metric for evaluating and optimizing campaigns. View-through attribution & reporting will not affect your media costs for Facebook CPM or CPC campaigns. Rather, view-through measurement gives you another valuable tool to improve your decision-making and optimization.

Singular view-through tracking utilizes the Facebook 1 day view window. Note that view-through attribution is enabled by default.

Reporting on Facebook Installs

Singular reporting for Facebook attributions utilize the values as named in your Facebook campaigns.

Facebook values are mapped to Singular reporting dimensions as follows:

Singular Value

Facebook Value

Example

Tracker Campaign Name

Campaign Name

MyCampaign

Tracker Campaign ID

Campaign ID

12345678

Tracker AdGroup Name

AdSet Name

MyAdGroup

Tracker AdGroup ID

AdSet ID

98123747

Tracker Creative ID

Ad ID

123192873

When running a Facebook report, Singular will also match the SDK data with the marketing data provided by Facebook Ads API, including:

Spend by Campaign

Spend by Creative, including the image or video

Account ID

Frequently Asked Questions (FAQ)

How does Singular track Facebook installs?

As a Facebook Mobile Measurement Partner, Singular has a unique line of communication with Facebook that enables attribution tracking. After the download of an application with Singular's SDK and Facebook Attribution Tracking enabled, Singular receives information about which installs originated from Facebook.

Are communications between Singular and Facebook secure?

Singular uses all the necessary security measures required by Facebook to ensure communications between Singular and Facebook are secure. We also comply with all of the privacy policies set forth by Facebook to protect your data.

I'm still not seeing Facebook attributed installs, where can I get help?

If you've followed the setup steps, but still aren't seeing Facebook attributed installs after performing your test, please contact Singular's Support Team for additional help. Please provide your account name, the applicable application, and your Facebook App ID in your initial email to help ensure a quick resolution.

With the Singular and Snapchat integration, you can track your Snapchat mobile app install campaigns in your Singular account. The integration is a server-to-server integration commonly referred to as a self-attributing method. This means configuration is simple, easy to set up, and doesn't involve the use of tracking links. For more information on advertising with Snapchat, see their advertising page or reach out to your Snapchat contact.

Integration Setup

Partner Configuration

Navigate to the page in your Singular Account.

Search for Snapchat in the partner search box:

Accept the Snapchat Terms & Conditions

Save the integration

Send Event Postbacks to Snapchat (Optional)

Singular supports sending event notifications to Snapchat with all of Snapchat's requirements.

First, select enable sending in-app events to Snapchat by selecting All.

Next, map your In-app events:

Select the event name on the left field, according to the name used in the SDK, and map the name to one of Snapchat predefined conversion events.

Check the Send value checkbox if relevant (for example, revenues). If not checked, only counts of the event will be sent.

Snapchat Reporting In Singular

Singular Value

Snapchat Value

Example

Tracker Campaign Name

Snapchat Campaign Name

MyCampaign

Tracker Campaign ID

Snapchat Campaign ID

123123

Tracker Creative ID

Snapchat Ad ID

123122

Note: Snapchat data sharing policies prevent the sharing of "Snapchat data" to 3rd parties. "Snapchat data" encompasses any data pertaining to an advertising ID belonging to a Snapchat user.

With the Singular and Oath/Yahoo Gemini integration, you can track your Oath mobile app install campaigns in your Singular account. The integration is a server-to-server integration commonly referred to as a self-attributing method. This means configuration is simple, easy to set up, and doesn't involve the use of tracking links.

Integration Setup

pixel ID (yp)

Navigate to the Partner Configuration page in your Singular Account.

Search for Yahoo Gemini in the partner search box:

Enter in your from your Yahoo Gemini dot tag page

Save the integration

Send Event Postbacks to Yahoo Gemini (Optional)

Singular supports sending event notifications to Yahoo Gemini.

First, select enable sending in-app events to Yahoo Gemini by selecting All.

Next, map your In-app events:

Select the event name on the left field, according to the name used in the SDK, and map the name to one of Yahoo Gemini predefined conversion events.

Check the Send value checkbox if relevant (for example, revenues). If not checked, only counts of the event will be sent.

Yahoo Gemini Reporting In Singular

Singular Value

Yahoo Gemini Value

Example

Tracker Campaign Name

Yahoo Gemini Campaign Name

MyCampaign

Tracker Campaign ID

Yahoo Gemini Campaign ID

123123

Tracker Creative ID

Yahoo Gemini Creative ID

123122

Learn about Singulars new methods for protecting customers from attribution fraud in Android devices and the Google Play Store.

Make sure to read Singular Fraud Prevention first for an introduction to Singular Fraud and a list of all available protection methods.

To learn how to activate and configure each fraud method, see Configuring Fraud Settings.

Android Install Fraud

What is Install Fraud?

While other types of attribution fraud rely on stealing the credit for legitimate app installs, install fraud is based on the creation of fake installs and fake users for the purpose of getting the installs attributed.

Install fraud appears in a variety of forms:

Device farms: Fraudsters get a large number of devices, use them to click on tracking links and install apps, then open the apps and delete them. The fraudsters reset each devices Android Advertising ID (or IDFA, on iOS) before the next use.

Emulators and bots: As a technological step up from device farms, emulators and bots are used to simulate having a lot of devices and a lot of people who click on tracking links and install apps.

SDK Spoofing: Instead of actually installing an app, the fraudsters fake the MMPs SDK traffic to send fake install reports.

Malware: Malicious apps install legitimate apps on users devices without the users knowledge or permission.

Fraud Prevention providers have mostly been using various statistical methods to detect install fraud, but these methods have weaknesses and fraudsters have found ways to work around them and avoid detection.

Solution: Android Install Validation

To tackle install fraud, Singular has developed Android Install Validation - a new, deterministic method of evaluating an install and making sure it is legitimate. Android Install Validation detects and prevents all known forms of fake install attacks at a significantly higher level of accuracy than any tools developed previously.

While the Google Play Store doesnt provide install receipts like the Apple App Store does, there are signals that the Play Store provides and Singular collects in order to make sure that the app was installed from the Play Store by a real Play Store user.

Singular also makes sure the same userisn'tresponsible for a large number of installs.

Notes:

Android Install Validation works only on installs coming from the Google Play Store (as most Android app installs do).

This method requires integrating the Singular SDK version 7.4.1 or above.

By Adding Your Google Play Licensing Key, Singular can verify install receipts cryptographically

Android Install Validation Best Practices

Use Custom Rules to Be Completely Protected

To avoid triggering Android Install Validation, fraudsters may try to have their app report that it was not installed from the Play Store and/or that the SDK version is older.

We recommend adding custom (user-defined) rules in order to:

1. Detect non Play Store installs

Detect installations outside of the Play Store for campaigns and sources that should point only at the Play Store.

Rule example:

Configuring User-Defined Fraud Rules

2. Detect installs by outdated SDK versions

Once you update the apps SDK, therearen'tsupposed to be any new installs of the app with an older SDK.

Rule example (make sure to specify the right SDK version for your app!):

To learn how to create rules, see Configuring User-Defined Fraud Rules.

Android Click Injection

What is Click Injection?

In click injection, the fraudster monitors a real users device for app installs - usually through a malicious app that has been installed on the device. When the user installs a new app, the malicious app creates a fake click (or impression) in order to hijack the app install attribution.

Solution: Detecting Injected Clicks

Singular uses Google Play Referrer values and timestamps to detect impressions and clicks that occur after users were directed to the Play Store or initialized an install. These fake impressions and clicks can then be rejected.

Android Organic Poaching

What is Organic Poaching?

In Organic Poaching, a fraudster claims credit for an app install that is in fact organic and should not be attributed to any source. This fraud can be achieved through either click spamming or click injection.

Organic poaching is costly for advertisers as it makes them pay for users who have in fact converted organically.

What is Singulars Solution?

Singulars Organic Poaching Protection method detects signals from the Google Play Store that an app install is organic (not associated with any ad clicks). Any clicks associated with this install can then be identified as an organic poaching attempt.

Note: This protection method may trigger high percentages if a network sends impressions instead of clicks. Customers can prevent this by using custom rules to apply Organic Poaching prevention only to relevant sources (see ).

Rejected & Suspicious Reporting

These are two customized Singular Reporting views for Rejected or Suspicious Attributions. They include the same powerful flexible pivot functions and enable the analysis of Fraud that was prevented alongside the Rejection/Suspicious Reason and the Estimated Saved Cost which is available due to Singulars unique cost data.

The Reason dimension which appears in both reports reflects the name of the Method/Custom Rule that has caused the rejection/suspicious flagging and can be used to gauge the effects and effectiveness of different rules.

The reports provide metrics for the amount and percentage of Rejected/Suspicious installs for the requested dimensions.

For example, a report generated for the App, Source and Rejection Reason dimensions with the Rejected Installs and Rejected Installs (%) metrics would show the following for each valid combination of app, source and reason:

The amount of Rejected Installs for the specific app, source, and reason.

The percentage of the rejected installs for the specific app, source and reason out of the total installs of the specific app and source.

Estimated Fraud CPI and Estimated Saved Cost are additional metrics that can be found only in the Rejected Report. They are defined as:

Estimated Saved Cost - an estimation of the cost of the fraudulent installs, based on the daily cost per source.

Estimated Fraud CPI - an estimation of the average CPI per fraudulent install, based on the estimated cost and number of rejected installs per source.

Protected Report

An attribution is considered protected if one or more of its associated touchpoints was rejected in the fraud prevention process. The protected report shows you these attributions and enables you to track who is targeted by fraud. For example, you can see how many of your Organic users are targeted or if a specific network or campaign are targeted more than others.

Its important to remember that the Sources, Campaigns and Publishers shown in the protected report are of legitimate attributions that were protected by Singular Fraud Prevention.

Use Mark as Suspicious before enabling Reject

Singulars Fraud Prevention Suite provides powerful tools that affect attribution decisions in real time. Both Singulars Prevention Methods and the users custom rules might run into edge-cases which produce unwanted behaviour in the form of false-positives or false-negatives.

Therefore the best practice for users leveraging Singulars Advanced Fraud Prevention tools is to start gradually:

Use Mark as Suspicious to test the rules on your data before switching to Reject. This will allow you to monitor the performance of these rules in the Suspicious Report without risking changes to your ongoing marketing campaigns or negatively impact your volume unexpectedly.

Once the rule has been tested, you should promote it to actively Reject to prevent CPI/CPA billing postbacks from being sent.

For example, you might find that most of your end-users come from blacklisted IPs because you target end users that use VPN services.

Leverage Custom Rules

Each application has its own fraud consideration therefore we recommend using the custom rules to fit Singular Fraud Prevention to your specific use-cases for example:

Whitelist partners that are guaranteed to not fraud you. For example internal crosspromo.

Use the rules to reject installs thatdon'tmatch a campaigns targeting options.

Leverage Singulars Alerts

Sometimes the best way to catch fraud is to look at KPIs.

Users can set alerts on specific KPIs to know when a source or a publisher performs extremely good or extremely poorly. These abnormalities hint at possible fraud.

After being alerted, the user may choose to set a rejection for the specific publisher, which can be done using the Fraud Preventions Custom User Rules.

Learn what postbacks Singular can send in cases of rejected and suspicious installs.

If you are a Singular partner, we recommend checking out the Fraud Postbacks FAQ for Partners instead.

In addition to sending install attribution postbacks to the relevant ad networks, Singular can also send postbacks about fraud decisions.

Types of Fraud Postbacks

The two types of fraud postbacks are:

Rejection postback:

Rejection postbacks are sent when an install would be attributed to a certain touchpoint (such as a click from a certain ad network), but the touchpoint is rejected by Singulars fraud prevention system. Rejection postbacks can be sent to the relevant ad network and/or the customers internal BI platform.

Notification about a suspicious install:

Singular can notify customers internal BI systems when an install is attributed to a touchpoint that is marked as suspicious. In this case, the attribution decision is not changed, but Singular informs the customer about the install's suspicious status by adding the fraud decision reason to the install postback that is sent to the customers internal BI platform.

Decision Reasons

Fraud postbacks include the reason why the touchpoint was rejected or marked as suspicious. The decision reason is either:

One of Singulars built-in protection methods, such as Blacklisted IPs or iOS Install Receipt Validation.

Or a custom rule the customer has set up.

Note: When sending a rejection postback to an ad network, the decision reason does not mention user-defined rules by name, in order not to expose the customers business logic. Instead, the reason is specified in general terms as User-defined Rule. The rule name appears only in postbacks sent to the customers internal BI platform.

The following table summarizes the differences between fraud postbacks and suspicious touchpoint notifications:

Fraud Decision

Attribution

Postback Type

Postback Sent To

Content of Decision Reason

Rejected

Install attribution is blocked

Rejection postback (separate postback)

Ad Network and/or Customers Internal BI

For ad networks: censored decision reason (user-defined rules are not mentioned by name) For internal BI: full decision reason (name of built-in method or user-defined rule)

Suspicious

Install attribution is not affected

Decision reason added to install postback

Customers Internal BI

Full decision reason (name of built-in method or user-defined rule)

Example: How Both Postbacks are Used in a Single Install

The following illustration shows a users timeline as it is examined by the fraud prevention system after an install event.

The attribution service has found two touchpoints associated with the install: Click 1 on an ad from Network A, and Click 2 on an ad from Network B. The fraud inspection rejects click 2 (the touchpoint closest to the install) and marks click 1 as suspicious.

In this case, the install is attributed to Network A for Click 1.

Singular sends the following postbacks:

Postback

Sent To

Notes

Rejection Postback

To Network B

With censored reason for Reject decision

Rejection Postback

To Customer's Internal BI (regarding click 2)

With full reason for Reject decision

Install Postback

To Network A

Install Postback

To Customer's Internal BI (regarding click 1)

With full reason for Suspicious decision

How to Enable Fraud Postbacks

Fraud postbacks are available to customers of Singulars fraud prevention service.

These postbacks are enabled per app site.

To enable fraud postbacks:

In the Singular platform, go to Attribution > Partner Configuration.

Under the relevant ad network or internal BI, find the desired app site and click the pencil button (edit configuration).

Select the Enable fraud postbacks checkbox and click Save.

Note: Fraud postbacks are currently only supported for some partners. Other networks will not show the fraud postbacks checkbox in the configuration window.

Advanced: Limitations and More Examples

The following additional limitations apply:

Only One Rejection Postback per Install

Rejection postbacks are only sent for one touchpoint per install - the touchpoint closest to the install).

Example:

In this example:

Fraud Engine Results

Click 2 (Network B) - touchpoint closest to the install: Rejected

Click 1 (Network A): Rejected

Final attribution decision

The install is marked as organic.

Singular sends the following postbacks:

Postback

Sent To

Notes

Rejection Postback

To Network B (regarding Click 2)

With censored reason for Reject decision

Rejection Postback

To Customer's Internal BI (regarding click 2)

With full reason for Reject decision

Install Postback

To Customer's Internal BI

Marking the source of the install as organic

No Fraud Postbacks if the Fraud Decision Didnt Affect the Attribution

Rejection postbacks are not sent for touchpoints other than the one the install would have been attributed to.

If a touchpoint closer to the install is judged to be valid or suspicious, and therefore the install is attributed to it, earlier touchpoints are still examined by the fraud prevention system. But even any of those earlier touchpoints are rejected, Singular does not send rejection postbacks for them.

Example:

In this example:

Fraud Engine Results

Click 2 (Network B) - touchpoint closest to the install: Valid Click 1 (Network A): Rejected

Final attribution decision

The install is attributed to Network B for Click 2.

Singular sends the following postbacks:

Postback

Sent To

Install Postback

To Network B (regarding Click 2)

Install Postback

To customer's Internal BI (regarding Click 2)

Learn about the purpose of deep-linking and what technologies are used to implement deep-links. For information about deep-linking in Singular, see the Singular Links FAQ and Singular Links Best Practices and Examples.

What are deep-links?

#

Deep-links drive returning users directly to the heart of your application, much like regular web links direct users to a specific page within a website. After doing a little leg work to implement deep-links in your app, you can lead users straight into your app to a specific screen, or create customized experiences the moment they enter the app.

How do deep-links work?

#

Developers have been using different methods to enable deep-linking:

Note: Singular Links technology was developed with iOS and Android deep-link trends in mind. When you generate a tracking link in Singular, the link is automatically enabled with the compatible deep-linking technology, including Apple Universal Links, Android app links, and Android intent technology. In addition, the Singular SDK is designed to simplify usage of deep-links and deferred deep-links. See the Singular Links FAQ for more information.

URI Schemes (e.g. "myapp://path/to/page?pageid=1"): In this legacy deep-linking method, the app developer registers a scheme for the app, so that the device platform knows it needs to open the app whenever a user clicks a link with that scheme - in our example, any link starting with myapp://.

If the app is installed on the device, it opens, and then parses the rest of the link and shows the user a specific page within the app or delivers a specific experience accordingly.

If the app is not installed on the users device, this results in an error. There is no fallback URL.

iOS Universal Links (iOS 9+): This technology was developed to improve on URI-scheme-based deep-linking on iOS. When using this technology, the app developer first sets up a verified web domain (e.g. "myapp.com") to serve Universal Links for an app. When a user clicks a Universal Link (e.g. "https://www.myapp.com/path/to/page?pageid=1"), the device platform knows it needs to open a specific app.

If the app is installed on the device, it opens, and then parses the rest of the link and shows the user a specific page within the app or delivers a specific experience accordingly.

If the app is not installed, the user is taken seamlessly to the web URL, using the devices default browser.

Android App Links (Android 6.0+): Android's improvement on URI-scheme-based deep-linking. When using this technology, the app developer first sets up a verified web domain to serve App Links. When a user clicks an app link, the device platform knows it needs to open a specific app.

If the app is installed on the device, it opens, and then parses the rest of the link and shows the user a specific page within the app or delivers a specific experience accordingly.

If the app is not installed, the user is taken seamlessly to the web URL, using the devices default browser.

What are deferred deep-links?

#

Deferred deep-linking is another improvement on deep-links. With this technology, if a user clicks on a deep-link and does not have the app installed on their device, not only is the user directed to an app store, but the deep-link parameters (what page or customized experience to show to the user) are actually not lost. If the user later installs the app from the app store, and opens it, the app accesses the deep-link parameters and shows the user the intended customized experience.

Unlike deep-linking, deferred deep-linking is generally only possible with the help of an attribution tracker:

The tracker collects information about pre-install touchpoints (clicks and views) meant for the mobile app.

The trackers SDK, implemented inside the app, can access that pre-install context.

The app uses the SDK to find out what deep-link the user originally engaged with and serve the intended page or customized experience when the app is opened for the first time.

What causes deep-linking to fail?

#

Though deep-linking is an incredibly useful way to engage with your users. However, to properly use it for your marketing channels, you should be familiar with its usage and limitations.

Limitations of URI Schemes

Using URI schemes is generally not recommended, because if the app is not already installed on the users device, clicking a link will cause an error and drastically reduce user engagement. You can work this on Android by using Android intents to direct the user to the Google Play store instead of being shown an error message.

In addition, URI-scheme deep-linking has security vulnerabilities: other apps can register the same URI scheme as your app and hijack your deep-links.

Limitations of iOS Universal Links

Social Media Apps: Some social media apps intentionally break or limit deep-links that try to take the user out of the social media app. These are often social media apps that open links in an internal web browser view.

Link Wrapping: Universal Linkscan'twork with link wrapping, where another URL redirects to the universal link. Link wrapping includes link shorteners such as bit.ly.

Pasting in Browser URL Field: Universal Links will not deep-link if you enter the link into a mobile browser's URL field.

Triggering Links with Javascript: Scripts that trigger URL redirects will not deep-link unless it is part of a user action.

Limitations of Android App Links

Social Media Apps: Some social media apps intentionally break or limit deep-links that try to take the user out of the social media app. These are often social media apps that open links in an internal web browser view.

This article offers advanced examples and best practices for using Singular Links. Be sure to read the Singular Links FAQ first.

In this article:

Deep Linking Tips

Passing Dynamic Data to the App with Passthroughs

Using Landing Pages

Limitations of Custom Sources

Adding Granularity Parameters for Custom Sources

Overriding Redirects for Links

Using Shortened Links

Note: Singular Links are being rolled out gradually to our customers, starting August 2019.

Deep Linking Tips

Use Cases

There are two ways to use deep links:

Use deep linking to direct the user to specific content in the app - like linking to a specific page in a website.

Take advantage of the data passed in a deep link to influence the users experience going forward. For example, in a shopping app, you can record a promo code associated with the ad that the user clicked, and then apply the code later during check-out.

Both approaches offer interesting options to engage users and help drive them to experiences in your app. Its important to understand what your engagement goals are and how they can be tied to those experience via deep links.

URL Structures

If your app was developed for multiple platforms, we recommend using the same deep link URL structure for all platforms. This will make it easier to enable deep linking in your Singular Links, as you will be able to use the same deep link URL for both versions of your app.

For example, if you have a clothes shopping app that has iOS and Android versions, make the following deep link URL work in both platforms to lead the user to a specific product:

myshoppingapp://path/to/product?productid=1234&category=shoes

Deferred Deep Links

Singular recommends designing and handling deferred deep links in the same way you handle deep links in your app.

Using Deep Links in Re-engagement Campaigns

Some partners that support re-engagement also support deep linking. Reach out to your partner to understand what deep linking options are available.

In some cases, partners support deep linking but allow the attribution provider to perform the deep link. If that is the case with your partner, make sure to generate the tracking link with the expected deep link URL in Singular.

Passing Dynamic Data to the App with Passthroughs

After you create a tracking link in the Link Management page, you can use it as-is in your campaign. However, you can make the link do even more work by adding data to it dynamically as you display your ads. This data can then be read and used by your app if a user engages with one of the ads and then arrives into your app.

You can do this by appending the _p query parameter, and any value, to a Singular Link. _p (for "passthrough" allows you to append any URL-encoded value to make that value available when the app is opened. The parameter supports structured (JSON) or unstructured strings.

For example:

Lets say you have a shopping app, and you show dynamic banner ads of different shoes on a mobile website. You have created a Singular Link that looks as follows: https://myshoppingapp.sng.link/A59c0/nha7

When you display the ad, the specific pair of shoes shown has a product ID, e.g. Shoes123.

You append the product ID to your Singular Link using the _p parameter.

The result: https://myshoppingapp.sng.link/A59c0/nha7?_p=Shoes123

Whenever a user engages with that banner and then installs and opens the app, your app can read the product ID using the Singular SDK. Your app team can use this information to personalize the users first app experience.

Passing JSON Objects

As the passthrough value is just a string value, you can pass even more information using JSON objects.

For example, you build a JSON object as follows:

{ productid:Shoes123, qty:1}

Then you URL encode it and append it to the _p parameter in your Singular tracking link. The result:

https://myshoppingapp.sng.link/A59c0/nha7?_p=%7B%22productid%22%3A%22Shoes123%22%2C%22qty%22%3A1%7D

Try It Out

Try passthroughs with our app by changing Shoes123 to different values:

https://singularassist.sng.link/A59c0/nha7?_dl=singularassist%3A%2F%2F&_p=Shoes123

Using Landing Pages

Use a landing page when your product needs an additional explanation in order to effectively convert a user.

If you decide that a landing page is right for your campaign, and your campaign depends on a mobile attribution provider for tracking, first consider the following:

Make sure there is a way for the user to convert to the app from the landing page.

Consider the media channel youre working with. Integrated partners may support different methods to execute a landing page.

Then, decide which touchpoint would you like to attribute the install to.

Tracking the click that takes the user to the landing page: In this case, just use the Singular Link you generate in the Link Management page as usual, and define the landing page as your Mobile Fallback URL (see the Singular Links FAQ ).

Tracking the click that the user engages with within the landing page: If you choose this option, embed the Singular Link is in your landing page. Make sure the link from the ad to the landing page passes any necessary tracking values through to the landing page.

Limitations of Custom Sources

You can use Singular Links to track your marketing efforts in self-owned channels such as social media or SMS. However, deep linking only works in some channels with some technologies.

Weve compiled a list of known and common redirect limitations:

Android

iOS

Fallback to Google Play Store

Deep Link

Fallback to App Store

Deep Link

Facebook Feed

Yes

Landing Page Required

Yes

Landing Page Required

Facebook Messenger

Yes

Landing Page Required

Yes

Landing Page Required

YouTube

Yes

Landing Page Required

Yes

Landing Page Required

Gmail

Yes

Yes

Yes

Yes

Instagram

Yes

No

No

Landing Page Required

LINE

Yes

Yes

Yes

No

Mail (iOS)

Yes

Yes

Yes

Yes

Messages (iOS)

Yes

Yes

Yes

Yes

Reddit

No

No

No

No

Slack

Yes

Landing Page Required

Yes

Landing Page Required

Twitter

Yes

Landing Page Required

Yes

Landing Page Required

WeChat

Yes

No

No

No

WhatsApp

Yes

Yes

Yes

Yes

Adding Granularity Parameters for Custom Sources

When you use Singular Links in custom sources, you can add dimension information in order to get that added granularity in your reports. For example, if you pass the campaign name in your tracking link, you will get campaign-level granularity in your report.

To pass the information, add it as a parameter value to the link when you serve it. For example, the following link records the Campaign Name dimension as CoolShoes123:

https://singularassist.sng.link/A59c0/u53f?_dl=singularassist%3A%2F%2F&_p=%7B%22productid%22%3A%22Shoes123%22%7D&pcn=CoolShoes123

See the full list of tracking link reporting parameters.

Overriding Redirects for Links

In some cases, you may want to dynamically modify redirects for existing Singular Links. This can be useful if youre serving a dynamic deep link based on some input from the user or on the context of the user engagement.

The following query parameters can be appended or modified as needed. Remember to URL-encode the value when appending it to a parameter.

Parameter

Description

_dl

Deep link for all mobile platforms. NOTE: Overriding/using this query parameter is only possible if the original link was enabled with deep linking.

_ddl

Deferred deep link for all mobile platforms NOTE: _ddl can be enable deferred deep linking even if not enabled via the UI during creation

_fallback_redirect

The fallback redirect for all platforms (web + any other platform)

_android_dl

Deep link for Android. This is typically used if your deep link URL on Android is different from your iOS app.

_android_redirect

Redirect URL if app not installed on Android. This is typically the app store URL

_android_ddl

Deferred deep link for Android. This is typically used if your deep link URL on Android is different from your iOS app. NOTE: _android_ddl can be enable deferred deep linking even if not enabled via the UI during creation

_ios_dl

Deep link for iOS. This is typically used if your deep link URL on iOS is different from your Android app. NOTE: Overriding/using this query parameter is only possible if the original link was enabled with iOS deep linking.

_ios_redirect

Redirect URL if app not installed on iOS. This is typically the app store URL.

_ios_ddl

Deferred deep link for iOS. This is typically used if your deep link URL on iOS is different from your Android app. NOTE: _ios_ddl can be enable deferred deep linking even if not enabled via the UI during creation

For example:

You have a Singular Link originally created to deep link to myapp://homepage: https://myshoppingapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fhomepage

You want to use that same link, but deep link to myapp://registration in some cases.

To achieve that, update the _dl= to the new value and use the same link: https://myshoppingapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fregistration

Using Shortened Links

After you generate a custom tracking link in Singular, you can shorten it by clicking Shorten Link.

This option is primarily useful for custom channels where the URL is exposed to the end-user, or for channels with restrictions on the length of the URL, such as SMS.

However, shortened links have another benefit: since the link does not contain parameters explicitly (instead, the parameters are resolved by Singular whenever the link is clicked), you can change these parameters in the Singular UI to update live campaigns directly.

For example, you may use a banner or landing page to track a regularly changing promotional offer. If you use a full-length Singular tracking link, you have to swap out the link whenever you want to change the promo details. If you use a shortened link instead, you can just update the promo details from the Singular Link Management page (by changing the link parameters).

Learn how to create and manage Singular tracking links through the Link Management page. For advanced usage tips, see Singular Links Best Practices and Examples.

Note: Singular Links are being rolled out gradually to our customers, starting August 2019.

Tracking Link Terms and Concepts

What is a tracking link?

#

When a user views or clicks on one of your ads, they are activating a link that notifies your attribution provider of the view or click. The attribution provider uses this information to track mobile app installs and re-engagements. The link can include other information, which will eventually be displayed in your reports.

What are Singular Links?

#

Singular Links are Singulars new tracking link solution. Marketers can create and manage their Singular Links through an intuitive UI that walks the user through all the available options for link behavior, attribution settings, and additional information to include in the link.

Singular Links automatically leverage iOS Universal Links and Android intent technology to create deeplinks whenever possible (see the Prerequisites ).

Here is an example of a Singular Link - you can try it out on your iOS or Android device:

https://singularassist.sng.link/A59c0/nha7?_dl=singularassist%3A%2F%2F

Note on legacy tracking links: In the documentation, we use the terms Singular Links and tracking links interchangeably. Your account may still have access to Singulars legacy tracking link solution. To avoid confusion, these will be referenced as legacy tracking links.

What is a deeplink?

#

Deeplinks are links that not only open the app on the users device (if the user already has the app installed) but also show specific app content or a specific user experience instead of just opening the apps default screen. Learn more in our Deeplinking FAQ.

What is a redirect?

#

When a user clicks a regular link on the web, such as www.linkedin.com, the browser asks the URLs server (in this case, LinkedIn) what it should do, and in return the URLs server gives the browser some HTML to display to the user.

When a user clicks a tracking link, the link providers server tell the users browser to go to a different URL instead (the redirect URL), and to serve the content from that URL. The redirection is usually performed via HTTP 302.

What is a fallback redirect?

#

In the context of deeplinking, a fallback redirect is a redirect destination that you want to take the user to in case the deeplink fails.

Typically, if a user clicks an ad for your app, you want the deeplink to send them into a specific screen inside the app. But if the user doesnt already have the app installed, you want to redirect the user to the app store instead, so they can download your app.

Creating Singular Links

What is a Link Sub-Domain?

#

Singular tracking links have the following structure, where [SUB-DOMAIN] is chosen by you:

https://[SUB-DOMAIN].sng.link/[PARAMETERS]

For example, for a campaign that markets an app called Jewel Rush, you can create the sub-domain jewelrush. Then you can use it to create tracking links with the following structure:

https://jewelrush.sng.link/[PARAMETERS]

You can create a single sub-domain and use it for all your links, or you can create several to use for different purposes. You have to create at least one sub-domain.

#

What is the Link Type? What is the difference between Partner links and Custom Source links?

#

Partners are services that are integrated with Singulars attribution service.

When you create a Partner link, Singular automates the process by:

Displaying only the options that are supported by that partner. For example, some partners support only iOS or only Android.

Generating the tracking link with partner macros that allow the partner to pass campaign information to Singular.

Custom Sources are self-owned or self-managed marketing channels such as email or SMS campaigns, social media, and cross-promotion campaigns.

Note: If you are working with an email service provider, create a Partner tracking link. If you manage your own email campaigns, create a Custom tracking link..

Whyisn'tFacebook/Twitter in the Source Name dropdown?

#

Self-Attributing Networks such as Facebook and Twitter do not use Singular tracking links. To configure them, see Attribution Integrations: Special Instructions.

What is the "Tracking Link Name"?

#

This is just a name you give your tracking link, and it can be whatever you want (although most users use the campaign name or a variation of the campaign name).

The Tracking Link Name will appear in your reports as Tracker Name.

Can I use the same tracking link for iOS and Android?

#

You can sometimes - depending on the partner.

Some partners support only iOS or only Android.

Others support both platforms, but require you to create a separate link for each.

Finally, some partners allow you to create multi-platform links, where you create one tracking link for use with both platforms.

The Create Link page displays the options that are supported by the partner you have selected.

Note: To make your link available for a certain platform, you first have to set up your app for that platform (add an app site) in Singular's Apps Configuration page.

See our Best Practices and Examples article for more information.

What is re-engagement?

#

Re-engagement means targeting existing users. Not all partners support this type of marketing campaign. If a partner does support the option and you want to use this Singular Link to track re-engagement as well as new installs, select Enable Re-engagement Tracking.

Why is Enable Re-engagement not available for a partner?

#

Some partners do not support re-engagement campaigns. If a partner does support re-engagement but the option is not available in Singulars Create Link/Edit Link page, please contact Singulars support team so we can update the integration.

Whats the difference between deterministic and fingerprinted clicks/views?

#

Deterministic clicks/views are those that are attributed to a source based on a device identifier or Google Install Referrer.

Fingerprinted clicks/views are attributed based on device fingerprinting methods, i.e. a combination of various properties that Singular gathers about the users device at the absence of a device ID.

See Device Fingerprinting Methodology for more information.

Why doesn't the page let me create a link?

#

Check if the link exists already. You cannot create a tracking link with the same source, tracking link name, and configured app site(s) as an already existing link.

How can I create a tracking link with a shorter URL?

#

Note: Link shortening is available for custom links only.

After you click Generate and see the tracking link URL, you can select Shorten Link to create a shorter version of the same link. This is useful for custom channels where the URL is exposed to the end-user, or for channels with restrictions on the length of the URL, such as SMS.

Tip: Shortened links can also be used to update live campaigns without having to swap out the tracking link. See Singular Links Best Practices: Using Shortened Links for more information.

Link Structure and Parameters

What do the different parts of a Singular Link mean?

#

This is an example of a Singular Link generated in the Create Link page:

https://nike.sng.link/C59c0/47bm?_dl=singular%3A%2F%2Ftestlink&idfa={idfa}&aifa={aifa}&pcn={campaign_name}&pcid={campaign_id}&pcrn={creative_name}&pcrid={creative_id}

The components of the link are:

Component

Example

Description

Subdomain

nike

The customizable subdomain of the tracking link.

Domain

sng.link

The domain of the tracking link.

App ID (Path)

C59c0

A Singular-generated ID representing the app. Used in conjunction with the Link ID to uniquely identify the tracking link.

Link ID (Path)

47bm

A Singular-generated ID representing the link information encoded in the tracking link. Used in conjunction with the App ID to uniquely identify the tracking link.

Query Parameters

_dl=singular%3A%2F%2Ftestlink &idfa={idfa}&aifa={aifa} &pcn={campaign_name} &pcid={campaign_id} &pcrn={creative_name} &pcrid={creative_id}

Optional parameters that add functionality and reporting granularity to the tracking link.

What query parameters can I use in a Singular Link?

#

See Tracking Link Parameters and Report Dimensions for the full list of query parameters.

Editing and Archiving Links

What happens if I edit a tracking link that is already being used?

#

The changes take effect as soon as you click Save in the Edit Tracking Link page.

If the link is already active in campaigns, any past clicks, impressions, and attributions belonging to these campaigns are not affected.

Note: We do not recommend editing live tracking links. The editing functionality is provided for adjusting settings or correcting mistakes in the campaign preparation stage. Editing a link after its live may have unintended effects on attribution.

What happens to a link when I archive it?

When you archive a tracking link, that link is hidden from your tracking link dashboard. The purpose is to declutter your dashboard by hiding old links that belong to past campaigns.

Archiving does not deactivate a link. If you archive a link that is still being used in a live campaign, the link will still redirect and attribute users.

Note: Archiving is not reversible!

Learn how to set up your iOS and Android apps in order to fully implement the new Singular Links - including deeplinking. For more information, see the Singular Links FAQ.

Note: Singular Links are being rolled out gradually to our customers, starting August 2019.

iOS Prerequisites

Singular uses iOS Universal Links for deeplinking on iOS. To enable your app to use Universal Links with Singular Links, follow these steps:

Configure at least one sub-domain for your links in the Link Management page in Singular. For more information, see the Singular Links FAQ.

Integrate the Singular iOS SDK by following the iOS section in the Singular SDK Guide. Make sure to implement the Singular handler to route deeplinks properly.

To set up Universal Links (deeplinking in iOS):

Log into the Apple Developer Portal.

Go to Identifiers and select the app that you want to add Universal Links support to.

Singular handler

In the Capabilities menu, check the Associated Domains checkbox, and click Save.

To add the "Associated Domains" entitlement to your app:

In XCode, go to Project settings > Capabilities > Associated Domains.

Add your Singular Links domains.

Copy your "App Prefix" (AKA "Team ID") from the Apple Developer Portal.

In Singular, go to Apps Configuration, find your app, expand the iOS app site settings, and paste the value in the Team ID field.

Android Prerequisites

Singular uses URI schemes and Android intents for deeplinking on Android. To enable your Android app for deeplinking with Singular Links, follow these steps:

Integrate the Singular Android SDK by following the Android section in the Singular SDK Guide.

Make sure to implement the to route deeplinks properly.

To configure your Android app to handle URI Scheme deeplinks, add an appropriate intent filter to your AndroidManifest.xml.

For example:

<intent-filter> <data android:scheme="singular-example" /> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /></intent-filter>

This configuration will allow your app to open links such as:

singular-example://your-sub-domain1.sng.link/Aabcd/1234

In Singular, go to Apps Configuration, find your app, expand the Android app site settings, and enter the Android scheme name in the Android App Scheme field (in the example above, the scheme name is singular-example).

This article is a guide to Apples new deep-linking technology.

To learn about deep-linking, see our Deep-Linking FAQ.

To learn about Singulars tracking links and all the different technologies they support, see the Singular Links FAQ.

What are iOS Universal Links?

#

Universal Links are Apples new deep-links, designed to replace the older URI-scheme deep-linking method. They are available for devices running iOS 9 and above.

While Universal Links allow for deep-linking behavior similar to URI schemes, they function very differently behind the scenes. Universal Links look like normal HTTPS URLs, e.g. https://www.linkedin.com. When a user clicks a Universal Click, the users device opens the app that the link was configured for. If the app is not installed on the device, the user is taken to the actual URL in their mobile browser.

See Apples Developer documentation.

How do I set up Universal Links for my app?

#

As an app developer, do the following to enable Universal Links in your app:

Enable Associated Domains in Your Apple Developer Account

Log into your Apple developer account and go to the app's ID page. Enable the Associated Domains app service. Take note of your Prefix (bundle ID) and your ID (team ID) - you will need them later.

Best Practices and Examples

Add Associated Domain Capability to Your Application

Add the "Associated Domain" capability to your app in Xcode, and add your web servers' domain as an associated domain.

Configure the Web Server

Create apple-app-site-association File

Using the Prefix and ID from your app page, configure a JSON formatted file like the following and host it on an HTTPS web domain that is accessible from the root.

For example, if you own the "https://www.mycompanywebsite.com/domain", your JSON file should be accessible at the URL "https://www.mycompanywebsite.com/apple-app-site-association". Note that the hosted file does not contain a .json file extension.

{ "applinks": { "apps": [], "details": [ { "appID": "A4GXBZ4XU7.my.cool.app", "paths": [ "/page/all/", "/user/saved/*"] } ] }}

The appID is your [teamID].[app bundle ID] and it identifies your app. The paths details valid content pages in your app. Apple recommends to keep paths short. Use a wildcard ("*") to specify all paths and use the "NOT" keyword to exclude paths, e.g. "NOT /user/saved/*". See Apple's documentation on enabling Universal Links for more information.

Handle Universal Links Code

The final step is to make sure that any Universal Link that opens your app is handled correctly. To do so, implement the application:continueUserActivity:restorationHandler: method in your application delegate.

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler{if ([userActivity.activityType isEqualToString: NSUserActivityTypeBrowsingWeb]) {NSURL *url = userActivity.webpageURL;// Put code here to take user to relevant content}return YES;}

How do I enable Universal Links in Singular?

#

Singular takes care of this automatically. After you set up Universal Links for your iOS app, when you create a Singular Link for your app and enable deep-linking, that link will automatically function as an iOS Universal Link - providing both deep-linking and a mobile fallback.

Why do Universal Links sometimes not work as tracking links?

#

Link Wrapping

Link wrapping, where another link redirects to the Universal Link URL, often causes deep-linking to fail (the user just gets taken to the mobile web page in their browser). This is because Apple wants user intent behind any rerouting, and a tracking link that redirects to another URL and results in deep-linking is not considered direct user intent. Therefore, you cannot use Universal Links with partners who link-wrap an attribution trackers tracking link.

To help understand and work around this industry-wide limitation, see our list of .

Tracking Without a Click

If a user clicks on a tracking-enabled Universal Link, and it deep-links the user into the app (because the app is installed), some attribution trackers may not be able to track this touchpoint because the device did not perform any HTTP request and therefore no click is registered.

Using Singular takes care of this problem for you, as Singular Links ensures complete acquisition and re-engagement tracking of both install links and deep-links.

The Google Play License Key is a cryptographic key provided by Google for your app in the Play Store. Singular can use this key to help validate information coming from Google to maximize protection from attribution fraud. To learn more about license keys, see Google's documentation.

To add your Google Play License Key in Singular:

Log into the Google Play Console.

Select the app to which you want to add signature verification.

In the sidebar, select Development Tools > Service & APIs.

Copy the license key from the Licensing & in-app billing section.

In the Singular platform, go toSettings > Apps, find the app in the list and click on the Android app site to open the settings.

Under Fraud Options, paste the key in the Play Store License Key field.

Learn about Singular's integration withTapjoy and how to addTapjoy as a partner for Singular's attribution service.

Integration Summary

(See Partner Integrations Glossary )

Partner

Tapjoy

Partner Type

Ad Network

Click Tag

Supported

View-Through

Supported

Re-engagement

Not Supported

S2S

Not Supported

Creatives

Supported

Publisher

Supported

Receiving All Installs

Supported

Receiving All Events

Supported

Prerequisites

Integrate the Singular SDK (see instructions ).

Get your App ID from Tapjoy.

To set up event postbacks, first talk with your POC about which App ID or Engagement ID you should use and map to the SDK event names.

Setup

See Partner Configuration for general instructions for setting up a partner.

For Tapjoy, you will also have to fill out the following special fields:

Field

Description

Tapjoy App ID

ID provided by Tapjoy for each app.

Tapjoy App Id/ Tapjoy Engagement ID

ID provided by Tapjoy for each postback.

To track installs on Chartboost, you need one tracking link created in Singular + one callback created in Chartboost, for each app.

Creating a Tracking Link

To create a regular tracking link for Chartboost, see Creating Tracking Links. You need a tracking link for each app.

Creating a Callback in Chartboost

The "Singular Callback" in Chartboost is used for any campaign you want to track. You create a callback for each app, and associate the callback to the tracking link created in Singular.

To create a callback:

Log into Chartboost and select Tools > Callbacks.

Select Add New Callback.

Slide Callback is to ON.

Name the Callback "Singular - App Name - Android - Callback" or "Singular - App Name - iOS - Callback".

Select "Advertiser" or "Publisher".

From the Template drop-down, select "Singular iOS Click" or "Singular Android Click".

In the Required Information window, associate your callback with your Singular tracking link by entering the value of the "st" parameter in the tracking link.

For example, if your tracking link for the app is

https://c.singular.net/api/v1/ad?st=149493603555

Enter the value 149493603555.

In App Selection, choose the 'click' option for each app to assign this callback.

In Campaign Selection, choose the 'click' option for each campaign to assign this callback.

Click Save.

Configuring event postbacks on Singular UI

Chartboost supports receiving only "__SESSION__" and revenue events, therefore, you should avoid configuring sending other events. In addition, they would like to receive these events from all networks - please check "All" when setting up the postback rules.

As a Twitter Mobile App Conversion Tracking (MACT) Partner, Singular tracks and measure installs and re-engagements for your Twitter campaigns.

To set up Twitter attribution tracking:

Integrate Your Mobile App with the Singular SDK or S2S API. For more information, see the Singular Developer Portal.

Create and provision your Twitter Ads account. Note that the account must be Twitter Ad enabled. For more information, see Twitter Help or contact your Twitter account manager.

Proceed to set up your Partner Configuration on Twitter:

Note: This next step will provision Singular as an app Mobile App Conversion Tracking partner, associated to your Twitter ads account. Only one MACT partner can be provisioned for an app at any given time.

Accept Twitter's Terms and Conditions.

Log in and link your Twitter Ads account with Singular. This should be the Twitter Ads account that is permissioned to manage campaigns for all your Twitter ad accounts if you have more than one.

organic tweets

Select the authorized accounts that are promoting your app and select Next.

Configure the Twitter integration like any other partner.

By default, installs are reported to Twitter to enable install attribution tracking. Select the Enable Re-engagement Tracking checkbox to have sessions reported to Twitter, to allow Singular re-engagement tracking.

You can also have Singular report post-install events to Twitter for conversion optimization and reporting. To enable this option, you must map the event to the desired Twitter Conversion event.

Twitter Reporting in Singular

Singular Value

Twitter Value

Example

Tracker Campaign Name

Twitter Campaign Name

MyCampaign

Tracker Campaign ID

Twitter Campaign ID

2xzbi

Tracker Ad Group Name

Twitter Line Item ID

aied2

Tracker Creative ID

Tweet ID

351166379755724804

Twitter Organic

Singular also tracks attributions from through the Twitter integration. These appear in reports under the source "Twitter Organic".

Learn about Singular's integration with Vungle and how to add Vungle as a partner for Singular's attribution service.

Integration Summary

(See Partner Integrations Glossary )

Partner

Vungle

Partner Type

Ad Network

Creatives

Supported

Publisher

Supported

View-Through

Supported

Re-engagement

Not supported

S2S

Not supported

Click Tag

Supported

Receiving All Installs

Supported

Receiving All Events

Supported

Prerequisites

Integrate the Singular SDK (see instructions ).

In Vungle, find and copy the Vungle App ID (you can find it by going to the Vungle dashboard and opening the apps Details window). If you havent set up the app in Vungle yet, see the instructions in Vungles Help Center.

Setup

See Partner Configuration for general instructions for setting up a partner.

For Vungle, you will also have to fill out the following special fields:

Field

Description

Vungle App ID

The App ID you got from Vungle (see Prerequisites).

Learn about Singular's integration with Liftoff and how to add Liftoff as a partner for Singular's attribution service.

Integration Summary

(See Partner Integrations Glossary )

Partner

Liftoff

Partner Type

Ad Network

Creatives

Supported

Publisher

Supported

View-Through

Supported

Re-engagement

Supported

S2S

Not supported

Click Tag

Supported

Receiving All Installs

Supported

Receiving All Events

Supported

Prerequisites

Integrate the Singular SDK (see instructions ).

Setup

See Partner Configuration for general instructions for setting up a partner.

For Liftoff, you will also have to fill out the following special fields:

Field

Description

Event Name

The name of the event you want to send to Liftoff

Singulars attribution service offers integrations with a large number of partners, including:

Ad networks and agencies: These partners usually use Singular tracking links when users click on the ads the network serves, and can receive information from Singular in the form of postbacks.

Self-attributing networks (SANs) such as Facebook and Twitter: These partners share click information with Singular so Singular can track install attribution. Sometimes SANs can also receive postbacks.

Third-party analytics platforms, BI systems, fraud analyzing services, etc.: These partners can receive information from Singulars attribution service in the form of postbacks.

Learn more about some of our major integrations.

We use the following terms to describe integration features:

Feature

Description

Click Tag

The partner sends clicks to Singular by using tracking links.

View-Through

The partner sends information about impressions (views) to Singular by using special tracking links. Partners who support this are ad networks that serve impressions campaigns.

Re-engagement

The partner supports re-engagement campaigns for the customer.

S2S (Server-to-Server)

In most cases, clicking a tracking link sends the user to the app store after they are redirected through Singular. In S2S, the user goes directly to the app store, and the partner sends the click information to Singular server-to-server.

Creatives

The partner includes creatives data in campaign-level data sent to Singular.

Publisher

The partner includes publisher data (data about the app or other product in which the ad was served) in campaign-level data sent to Singular.

Receiving All Installs

Whether the partner supports receiving postbacks about all installs from Singular, or just about installs attributed to that partner. For more information about the option to send all installs to a partner, see Partner Configuration.

Receiving All Events

Whether the partner supports receiving postbacks about all in-app events, or only about in-app events following installs that were attributed to that partner.