Generic Attribution Partner
Understand how to leverage CleverTap APIs to push these events to CleverTap
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:
- Perform the server-side integration at their end.
- 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.
- 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}×tamp={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:
Parameter | Description | Mandatory |
---|---|---|
Campaign Source (utm_source) | Used to identify the source of your traffic. This could be a website name, search engine, newsletter name, or social network. For example, utm_source=google. |
|
Campaign Medium (utm_medium) | Used to identify the medium used to share and access your link. This could be email, social, cost per click (cpc), or any other such method. For example, utm_medium=cpc. |
|
Campaign Name (utm_campaign) | Used to identify a campaign or promotion tied to your link. This could be a product name, type of sale, contest name, etc. For example, utm_campaign=summer-sale. |
|
Device Identifier | Helps to identify the device to which you must map the attribution data, | Yes |
Event Type | Indicates the type of data received:
| Yes |
Partner Name |
| Yes |
Account Id, Account Token, and Account Passcode | Helps validate customer account before capturing the data | Yes |
Platform | Indicates the application platform. For example, Android, iOS, React Native, etc. | Yes |
Timestamp |
| No |
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×tamp=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×tamp=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×tamp=1656317838&device_identifier=__g1234abc&items=shoes&price=12.00&account_id=W6W-797-865Z&account_token=aca-060&account_passcode=1f81b71b91d84885a898911ab8722f34&platform=android×tamp=1660717763
Region Mapping for API Endpoints
This section provides a region-wise mapping of API endpoints.
Region (Data Center) | API Endpoint | URL |
---|---|---|
EU (Europe) This is the default data center. | https://api.clevertap.com/ | https://api.clevertap.com/attribution?partner_name=airbirdge&event_type=custom&device_identifier={CLEVERTAPID}×tamp=1656317838&platform=android&android_id=&city=Mumbai&match_type=gp_referrer |
IN (India) | https://in1.api.clevertap.com/ | https://in1.api.clevertap.com/attribution?partner_name=airbirdge&event_type=custom&device_identifier={CLEVERTAPID}×tamp=1656317838&platform=android&android_id=&city=Mumbai&match_type=gp_referrer |
US (U.S.A) | https://us1.api.clevertap.com/ | https://us1.api.clevertap.com/attribution?partner_name=airbirdge×tamp=1656317838&event_type=custom&device_identifier={CLEVERTAPID}&platform=android&android_id=&city=Mumbai&match_type=gp_referrer |
SG (Singapore) | https://sg1.api.clevertap.com/ | https://sg1.api.clevertap.com/attribution?partner_name=airbirdge&event_type=custom&device_identifier={CLEVERTAPID}×tamp=1656317838&platform=android&android_id=&city=Mumbai&match_type=gp_referrer |
SK (South Korea) | https://sk1.api.clevertap.com/ | https://sk1.api.clevertap.com/attribution?partner_name=airbirdge&event_type=custom×tamp=1656317838&device_identifier={CLEVERTAPID}&platform=android&android_id=&city=Mumbai&match_type=gp_referrer |
Indonesia | https://aps3.api.clevertap.com | https://aps3.api.clevertap.com/attribution?partner_name=airbirdge&event_type=custom×tamp=1656317838&device_identifier={CLEVERTAPID}&platform=android&android_id=&city=Mumbai&match_type=gp_referrer |
Middle East (UAE) | https://mec1.api.clevertap.com | https://mec1.api.clevertap.com/attribution?partner_name=airbirdge&event_type=custom×tamp=1656317838&device_identifier={CLEVERTAPID}&platform=android&android_id=&city=Mumbai&match_type=gp_referrer |
Callback Error Codes
The following table lists down the callback error codes:
Error Code | Description |
---|---|
200 | Ok - Success Indicates that the data was successfully sent to CleverTap. |
401 | Authorization error |
400 | Bad request.
|
5XX | Service Unavailable. Please retry later. |
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.
Updated 10 months ago