Overview

CleverTap partners with various attribution providers that help customers to know where their users are coming from and how they should engage with them. CleverTap allows attribution partners to push the following events:

• Organic attribution events
• Inorganic install attribution events, and
• Custom events

Acceptance Criteria

Any attribution partner can integrate with our open APIs, but they must perform the following steps to be visible on the CleverTap dashboard:

1. Perform the server-side integration at their end.
2. After integrating, reach out to us at [email protected] for the following:
   • Share the name of customers interested in the integration
   • Get yourself whitelisted on the CleverTap dashboard.
   • Share details about the type of data to be sent to CleverTap: Organic install, Inorganic install, or Custom events.
3. Create a document and share it with CleverTap team in a .md format. Also, provide your company logo in the SVG format with a transparent background. The size of the logo must be 40 x 40 px.

After CleverTap tests the integration, the partner is then listed on our Settings > Partners page.

Prerequisites for Integration

The following are the prerequisites for integrating with CleverTap:

• Partner dashboard must accept the following authentication parameters: Project Id, Project Token, Project Passcode, and CleverTap Region.
• Client SDK must capture CleverTap identifiers.
• Ability to call different CleverTap endpoints based on the CleverTap credential configuration.
• Ability to differentiate between Organic and Inorganic install attribution events.

Integrate with CleverTap

Workflow

This figure explains the exact process of how the information flows from the application to the CleverTap dashboard:

Get CleverTap ID

CleverTap uses the Device Identifier key-value parameter to attribute the partner attribution data to the right user. After integrating the CleverTap SDK, the value for the Device Identifier becomes available. If the device_idetifier is empty, CleverTap does not process the data.

For Android

Add the following code to your Android app code:

• For SDK version 4.2.0 and above

cleverTapInstance.getCleverTapID(new OnInitCleverTapIDListener() {
   @Override
   public void onInitCleverTapID(final String cleverTapID) {
       // Callback on main thread
       ;
   }   
});

• For SDK version 4.1.1 and below

String attributionID = cleverTapInstance.getCleverTapAttributionIdentifier();

For iOS

Add the following code to your iOS app code:

[CleverTap autoIntegrate];
[[PartnerSDK sharedTracker] setCustomerUserID:[[CleverTap sharedInstance] profileGetCleverTapAttributionIdentifier]];

For React-Native

Add the following code to your React Native app code:

CleverTap.profileGetCleverTapAttributionIdentifier((err, res) => { 
const userId = res;
});

API Endpoint Format for Capturing Inorganic, Organic, and Custom Events

To push data from your server to CleverTap, use the following API endpoint format:

API Endpoint Format

https://{REGION.}{ENDPOINT}/attribution?partner_name={PARTNERNAME}&event_type={TYPEOFDATA}&timestamp={EPOCH VALUE}&utm_source={UTMSOURCE}&utm_medium={UTMMEDIUM}&utm_campaign={UTMCAMPAIGN}&device_identifier={CLEVERTAPID}&account_id={PROJECTID}&account_token={PROJECTTOKEN}&account_passcode={PASSCODE}&platform={Android/iOS}

The following table provides information about the API endpoint parameters:

📘

For CleverTap to accept the attribution data, it is mandatory to provide at least one of the following parameters: Campaign Source (utm_source), Campaign Medium (utm_medium), or Campaign Name (utm_campaign).

📘

Additional API Endpoint Parameter

Apart from the parameters listed in the above table, CleverTap processes the additional parameters without any validation.

• API Endpoint for Organic Install
  The following is the sample API endpoint for the organic install event:

https://api.clevertap.com/attribution?partner_name=airbridge&event_type=organic_install&utm_source=utm_google&utm_medium=gd&utm_campaign=adir&device_identifier=__android11235&account_id=W6W-797-865Z&account_token=aca-060&account_passcode=1f81b71b91d84885a898911ab8722f34&platform=android&timestamp=1660717763

• API Endpoint for Inorganic Install
  The following is the sample API endpoint for the inorganic install event:

https://api.clevertap.com/attribution?partner_name=airbirdge&event_type=inorganic_install&utm_source=utm_google&utm_medium=gd&utm_campaign=adir&device_identifier=__android11235&account_id=W6W-797-865Z&account_token=aca-060&account_passcode=1f81b71b91d84885a898911ab8722f34&platform=android&timestamp=1660717763

• API Endpoint for Custom Event
  The following is the sample API endpoint for the custom event:

https://api.clevertap.com/attribution?partner_name=airbirdge&event_type=Add_to_cart&timestamp=1656317838&device_identifier=__g1234abc&items=shoes&price=12.00&account_id=W6W-797-865Z&account_token=aca-060&account_passcode=1f81b71b91d84885a898911ab8722f34&platform=android&timestamp=1660717763

Region Mapping for API Endpoints

This section provides a region-wise mapping of API endpoints.

Callback Error Codes

The following table lists down the callback error codes:

Sample Response

{
  "status": "fail", 
  "error": "Invalid Account Info", 
  "code": 401
}

{
    "status": "fail",
    "error": "utm_source is missing",
    "code": 400
}

FAQs

Q. What attribution data is accepted by CleverTap?

Ans: CleverTap accepts the following three types of data from our attribution partners:

• Inorganic Install Events
• Organic Install Events
• Custom Events

For more information about these events, refer to Types of Data. CleverTap accepts Inorganic install events from Attribution partners by default. Organic Install and Custom events must be enabled from the CleverTap dashboard by navigating to Settings > Partners page.

Q. Where can I find the CleverTap project details?

Ans: CleverTap Project ID, Token, Passcode, and Region is available under Settings > Project on the CleverTap dashboard

Q. Is there any validation API for validating credentials?

Ans: No. Currently, CleverTap does not have an API for validating credentials. So, we recommend trimming the spaces before saving the credentials on the partner dashboard.

Q. Any recommendation for integrating with CleverTap?

Ans: Yes, we recommend that for Project ID, Token & Passcode, it should be a text input field accepting alphanumeric characters. For Region, we recommend a dropdown for input with the options EU, US, IN, SG & SK, defaulting to EU.

Q. Is batching supported for API?

Ans: No.

Q. What are the different errors that we can encounter when performing generic partner attribution integration?

Ans: The following are the different errors that we can experience when performing this integration:

• Inorganic Installs: Retry with an exponential back-off in case of 500X errors.
• Organic Install: Retry with an exponential back-off in case of 500X errors.
• Custom: Retry with an exponential back-off in case of 500X errors.
• Compulsory parameter missing or Empty: It throws HTTP 400 and does not retry.
• Authorization error: It throws HTTP 403 and does not retry.

📘

Error 500X for More than 10 Minutes

Write to [email protected] if you observe a 500X error for more than 10 minutes or 99.5% SLA (CleverTap System Status).

Q. When does the response timeout?

Ans: 60 seconds.

Q. How can I confirm that CleverTap is recording attribution events?

Ans: For organic and inorganic events, CleverTap captures the data under the UTM Visited event. You can filter data by UTM Visited by navigating to Analytics > Events from the dashboard.

For Custom events, CleverTap captures the data by adding a prefix to the event name. For example, if the partner name is attribution partner and the custom event is Checkout, we save it as AP_Checkout.