In order to make use of the functionality mentioned in this article, you must have access to the app’s API key and your personal key. For more information, see Where do I find my API key and personal key? A good understanding of how to send events is also required. For more information about the Swrve Events API, see Swrve Events API.
For technical information about user acquisition tracking in Swrve, see User acquisition tracking guide. For information about the User Acquisition report, which enables you to track the results of user acquisition campaigns, see User Acquisition report.
All API calls to <app_id>.api.swrve.com (or <app_id>.eu-api.swrve.com for EU-configured apps) are authenticated using the API key provided for the app.
Tracking referral source
The following sections describe how to track the referral source using a tracking link.
Encode referral source in landing page URL
When your user acquisition team creates a landing page URL for your web app, they must add the following two parameters to the URL:
- swrve.provider – the name of the ad provider. Examples: Facebook, Nanigans.
- swrve.campaign – the name of the ad campaign being run. Examples: HappyNewYear, US_Females_25_30
For example, if your landing page URL is usually https://apps.facebook.com/my_app_name, add these two parameters to it:
Swrve currently supports only two hierarchical levels: provider and campaign. If you have feedback on how you’d like to see Swrve organize your referrers, please send your feedback to firstname.lastname@example.org or contact your CSM.
Decode referral source and send to Swrve
You must decode these parameters from the URL and combine them into a single string with a ‘.’ in between. For example:
swrve.provider + '.' + swrve.campaign = Facebook.HappyNewYear
Then send these combined parameters to Swrve in the swrve.referrer_id attribute of a User API call. For more information about User API calls, see Swrve Events API. Send this message once after the user installs your app. For example:
Sending referrer updates
You supply referrer updates to Swrve by sending a user event with a swrve.referrer_id parameter for a user of interest.
Useful user event parameters
|api_key||Required||The API key used to validate your events.|
|user||Required||The Swrve user ID.|
|swrve.referrer_id||Required||The name of the user’s referrer.|
|swrve.referrer_cost||Optional||The referrer cost of acquisition for this user in dollar cents. If this parameter is not specified, it is set to 0 by default.|
|user_initiated||Optional||If this parameter is specified and has the value false, then this event does not count towards some performance indicators such as DAU and MAU. If this parameter has any other value, or if the parameter is not present or is not specified, then the event counts towards all performance indicators as normal.|
Update or set the referrer of a user without affecting DAU and MAU. In this example, it costs $1.50 to acquire the user:
curl -G -d "api_key=<api_key>" -d "user=<user_id>" -d "swrve.referrer_id=my_advertising_partner" -d "swrve.referrer_cost=150" -d "user_initiated=false" https://<app_id>.api.swrve.com/1/user
curl -G -d "api_key=<api_key>" -d "user=<user_id>" -d "swrve.referrer_id=my_advertising_partner" -d "swrve.referrer_cost=150" -d "user_initiated=false" https://<app_id>.eu-api.swrve.com/1/user
If an error occurs while processing the request, you may receive one or more of the following error codes and need to make sure your integration is equipped to handle error conditions.
|400||Invalid Parameter||The request included an invalid parameter, based on the specification.|
|403||Invalid API Key||Check that your API key is correct.|
|410||API key no longer valid||The API key is not recognized, possibly due to the app having been removed from the system. Check that the API key and app ID are correct.|
|503||Service Unavailable||An error occurred on the Swrve server side. Attempt to resend the request later, if possible.|
This API call has been deprecated and any attempt to use the URL https://dashboard.swrve.com/api/1/exporter/referrer/ will return an error message. If you want to view or export user acquisition data, see User Acquisition report.