Setup Guide

Follow this guide to integrate the @ref247/affiliate-sdk into your application.

Frontend Integration

1. Use Tracking Links

Instead of directly calling the API with your secret key, affiliates will integrate using tracking links. Each tracking link points to your platform’s redirect endpoint, logs the click, and then forwards the user to the advertiser landing page. The Affiliate can find (or generate) his tracking link inside the Links page.

Example endpoint: Tracking Redirect API

# Normal customers
                            https://ref247.io/api/tracking?linkUri=456

                            #Enterprise customers
                            https://yourtrackingdomain.com/tracking?linkUri=456

2. Example in a Frontend App

Affiliates simply use the tracking link in their websites, ads, or email campaigns. No SDK or API key is required on the frontend.

export default function PromoBanner() {
  return (
    <a href="https://yourtrackingdomain.com/tracking?linkUri=456">
      <img src="/promo-banner.png" alt="Special Offer" />
    </a>
  );
}

3. Landing Pages

The final landing page of an affiliate link is determined by the campaign that the link is associated with. This means you don’t need to hardcode landing pages in your frontend — they are managed directly from the campaign configuration. You can set or update a campaign’s landing page from the Campaign Management Dashboard.

When redirecting to your landing page, ref247.io will include the following Query Parameters: affId & linkUri. These should be stored in local storage and then used throughout the signup process. The affId would be the parent affiliate of the user signing up. We provide an embed script to automate the storing of this data.

// in your landing pages
                            <script src="https://cdn.ref247.io/embed.umd.js"></script>

                               // in signup process
                               const data = Ref247TrackerEmbed.getData()
                               console.log('Ref247 embed data:', data);

                               // use data.affId

We also offer an npm package for ease of use: tracker-embed

4. Why This Approach?

Protects your private API keys (not exposed in frontend code)
Ensures all clicks are tracked before redirecting
Campaign landing pages can be updated anytime without changing links

Backend Integration

1. Install the SDK

npm install @ref247/affiliate-sdk

Or use our Rest API directly

2. Initialize with API Key

Import the SDK into your backend and initialize it with your API key generated from your Dashboard API Keys page.

import { AffiliateClient } from "@ref247/affiliate-sdk";

const client = new AffiliateClient({
  apiKey: process.env.REF247_API_KEY,
  baseUrl: "https://api.ref247.io",
});

3. Create an Affiliate

Before generating tracking links, you need to create an affiliate in the system. You can do this using the documentation: Add Affiliate.

externalUserId should be used to reference the ID of this user in your backend system. This isn't used by ref247.io except for your reference. In case this affiliate has a parent, you can also set the affiliateParentId field to create a hierarchy.

const affiliate = await affiliateSdk.createAffiliate({ name: 'Affiliate Name', email: '[email protected]', externalUserId:'YOUR_ID' });
                            const ref247AffiliateId = affiliate.id;

4. Example: Attributing events

This is used to send secure server events to ref247.io, example when deposits, trades, wins, losses, purchases, etc.. happen. We support an unlimited number of events and currencies, as they are customizable in the events & currencies pages. You can create your own fake bonus currency/coin and track it as well.CreateReferralAction Reference

const eventTypes = await client.getOrganizationEventTypes(orgId);
                                const currencies = await client.getOrganizationCurrency(orgId);
                                // affiliationId = is the data.affId retrieved during signup process
                                const message = await client.createReferralAction({eventTypes[0],affiliationId,amount,currencies[0],orgId});

5. Example: Fetch Campaigns

async function getCampaigns() {
  const campaigns = await client.getAllCampaignsOfOrganization(orgId);
  console.log(campaigns);
}

Next Steps

Explore available endpoints in the API Docs
Configure error handling and retries
Keep your API keys safe using environment variables