Last modified January 15, 2021 by Shelly Wolfe

Swrve Referrer API

This article explains how to send and access referrer information through the Swrve user acquisition campaign tracker.

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.

This article references Swrve’s URLs for all data and content stored in both our US and EU data centers. Click the relevant tab based on your app configuration. For more information, see How do I configure the Swrve SDK for EU data storage?

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:

https://apps.facebook.com/my_app_name?swrve.provider=Facebook&swrve.campaign=HappyNewYear

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 support@swrve.com 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:

US

https://<app_id>.api.swrve.com/1/user?api_key=<api_key>&user=<user_id>&swrve.referrer_id=Facebook.HappyNewYear

EU

https://<app_id>.eu-api.swrve.com/1/user?api_key=<api_key>&user=<user_id>&swrve.referrer_id=Facebook.HappyNewYear

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

Parameter Presence Description
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.

Example

Update or set the referrer of a user without affecting DAU and MAU. In this example, it costs $1.50 to acquire the user:

US

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

EU

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

Error codes

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.

Code Text Description
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.

Referrer export

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.