Tracking without fpr.js

Track affiliate leads and sales/payments using API calls

Planning to use sub IDs, postbacks or ad tracking? You still need the tracking script for clicks. See Using sub IDs, postbacks or ad tracking with the API below.

Tracking Flow

1. Store and retrieve link token (Referral ID):

When a visitor arrives through a referral link (e.g., https://yourdomain.com?fpr=joe13, where fpr is the affiliate’s Referral ID parameter and joe13 is the value), retrieve the referral link token (Referral ID) from the referral link, store it in the browser’s localStorage or as cookie for later use.

The available query parameters are ?fpr, ?via, ?fp_ref, ?deal, ?ref, ?_from, ?_by, ?_go .

I. Store referral link token implementation

client side (localStorage implementation)

<script>
// Function to store referral link token in localStorage
function storeReferralLinkTokenInLocalStorage(referralLinkTokenParam) {
    // Get URL parameters
    const urlParams = new URLSearchParams(window.location.search);
    const referralLinkToken = urlParams.get(referralLinkTokenParam.replace("?",""));

    if (referralLinkToken) {
        localStorage.setItem('_fprom_ref', referralLinkToken);
    }
     else{
        console.log(`No such query parameter '${referralLinkTokenParam.replace("?","")}' or '${referralLinkTokenParam}' found in ${window.location.search}`);
    }
}

// Call the function to store the Referral ID/token when the page loads by passing the query parameter.

storeReferralLinkTokenInLocalStorage('fpr');
</script>

II. Retrieve referral ID/token

client-side (localStorage implementation)

<script>
// Function to retrieve referral ID/token stored in localStorage
function getReferralLinkToken() {
    return localStorage.getItem('_fprom_ref');
}

// Call the `getReferralLinkToken` function whenever you want to get referral ID/token on any of the pages.

var ref_id = getReferralLinkToken();
</script>

2. Lead/Referral tracking

When a visitor signs up or fills an opt-in form, convert them to a referral by using the track/signup endpoint.

You can send only the email or only the uid or both. You need to ensure that the actual visitor data is passed in the API call.

curl --request POST \
  --url https://api.firstpromoter.com/api/v2/track/signup \
  --header 'Account-ID: <account-id>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
	  "email": "[e-mail]",
	  "uid": "cus_000001",
	  "ref_id": "joe13",
	  "skip_email_notification": true
}'

Using sub IDs, postbacks or ad tracking with the API

If you want to use sub IDs, postbacks or ad tracking, sending ref_id to track/signup is not enough. These features rely on data captured when the visitor clicks the referral link: the sub ID (fp_sid) from the link, the landing page URL with any ad click IDs, and the visit itself. FirstPromoter only records that data when the click is tracked by the tracking script, and only links it to the referral when you send the visit’s tid.

A signup tracked with only ref_id is credited to the right affiliate, but it has no click attached. Its sub ID will be empty, postback values that come from the visit will be blank, and ad traffic can’t be detected.

To keep this data, use the tracking script for clicks and the API for signups:

1. Install the main tracking script

   Add the main tracking script to every page a referral link can land on. When a visitor arrives through a referral link, the script tracks the click and sets the _fprom_ref and _fprom_tid cookies.

   If visitors land on one domain and sign up on another, set up cross-domain tracking so the cookies are available where the signup happens.

2. Read the _fprom_tid cookie at signup

   When the visitor signs up, read the _fprom_tid cookie on your server (or in the browser and send it to your server with the signup form).

3. Send it as tid to track/signup

   Pass the cookie value in the tid parameter of track/signup. FirstPromoter uses it to find the tracked click, credit the right affiliate, and attach the sub ID, landing URL and ad data to the referral.

Server side (Express)

const express = require('express');
const cookieParser = require('cookie-parser');

const app = express();
app.use(cookieParser());
app.use(express.json());

app.post('/signup', async (req, res) => {
  // Set by the FirstPromoter tracking script when the visitor clicked a referral link
  const tid = req.cookies['_fprom_tid'];

  // ...create the user in your app...

  if (tid) {
    await fetch('https://api.firstpromoter.com/api/v2/track/signup', {
      method: 'POST',
      headers: {
        'Account-ID': '<account-id>',
        'Authorization': 'Bearer <token>',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email: req.body.email, uid: req.body.uid, tid }),
    });
  }

  res.sendStatus(201);
});

If there is no _fprom_tid cookie, the visitor didn’t arrive through a tracked referral link (or their browser blocked the cookie), so don’t send an empty tid. If you still know the referral ID, you can send it as ref_id instead, but sub IDs, postback visit data and ad tracking won’t be available for that referral.

3. Sales Tracking

If you are using Stripe, Chargebee, Braintree, Paddle or Recurly we can track sales automatically on our end. You will only need to connect your billing provider to FirstPromoter.

If you use any other billing provider you will need to track sales using the tracking API. For more information on sales tracking API, see documentation here

When a sale event is received, FirstPromoter will automatically:

• Identify the corresponding affiliate to assign the sale to.
• Assign the corresponding reward/commission to the promoter.

With this in place, you have completed the basic tracking flow. From storing and retrieval of affiliate referral link token (Referral ID) through to assigning the corresponding commissions to the affiliates.