Server side Tracking

This page presents two HTTP post API endpoints that can be used for tracking from your server

Note:

1. To be able to query below APIs from a server, it will be required to pass API secret keywith each request for authentication.

2. Please store the API secret key safely as an environment variable on the server.

setReferral

This API can be used for user action like connecting wallet on your website and signing up, where we will register the user as referred invitee on success.

setReferral

POST https://us-central1-qwestive-referral-prod.cloudfunctions.net/setReferral

Register invitee for the referrer with user's public wallet key and set the current user as the registered invitee in the campaign

Headers

Name	Type	Description
Content-Type	String	application/json

Request Body

Name	Type	Description
secretApiKey*	String	Secret API key which authenticates the calling server
projectId*	String	Unique projectId
publicKey*	String	User's public wallet key
referralCode*	String	Unique code of referrer

200: OK Invitee registered successfully

// Return the user's public wallet key
{
    "result": {
        "publicKey": "user_public_wallet_key"
    }
}

400: Bad Request Please provide projectId

401: Unauthorized Unauthorized Access: Invalid API Key

400: Bad Request Please provide public key of the user

400: Bad Request Please provide a valid referralCode

400: Bad Request Provided referralCode does not belong to project

403: Forbidden User cannot invite themselves in the campaign

403: Forbidden User cannot invite other referrer in the campaign

200: OK Invitee already invited in the campaign

{
    "result": {
        "publicKey": "user_public_wallet_key",
        "isRegisteredInvitee": true,
        "message": "Invitee already invited in the campaign"
    }
}

500: Internal Server Error Internal Server Error

Sample cURL

curl --location 'https://us-central1-qwestive-referral-prod.cloudfunctions.net/setReferral' \
--header 'Content-Type: application/json' \
--data '{
    "secretApiKey": "Or5rr4ssalLD1TpU1HhoHsJ03q00IO32MUSeXeyueQE=",
    "projectId": "7VveXIwMqTmecXhkjkUD",
    "publicKey": "InviteeNRooBzvZ1WB3UJvQqM8R2CiGcaaEREXMg123",
    "referralCode": "rcwgS"
}'

Please note, setAlias has been renamed to setReferral for better naming convention and avoiding any ambiguity. Though, setAlias endpoint is still available, but shall be deprecated soon.

setConversionEvents

This API can be used for sending conversion events with conversion value and revenue value for users already registered in the campaign as invitees.

setConversionEvents

POST https://us-central1-qwestive-referral-prod.cloudfunctions.net/setConversionEvents

set conversion events for invitees with conversion value and revenue value for a campaign

Request Body

Name	Type	Description
projectId*	String	Unique id of the project
campaignId*	String	Unique id of the campaign
events*	Array	checkout conversion event spec below
secretApiKey*	String	Secret API key which authenticates the calling server

200: OK list of successful invitees and failed invitees

{
    successfulInvitees: [],
    failedInvitees: [],
}

400: Bad Request Number of events cannot be more than 500

when API hits the limit of supporting at max 500 events

400: Bad Request Please provide valid events

when all events don't have a valid wallet address and both conversion value or revenue value does not exist on each event.

500: Internal Server Error Failed to process invitees

Note:

1. Supports batch of multiple conversion events per invitee.

2. Each conversion event should belong to registered invitees only, otherwise it will simply fail for unregistered invitees. (setReferral must have called for each invitee)

3. Number of conversion events can be 500 as max and 1 as minimum to be processed successfully

4. Supports both positive and negative revenue values.

5. Returns successfulInvitees and failedInvitees as response

Conversion event spec

interface TokenSpec {
  // The chain this token is on.
  chainId: 'eth' | 'sol' | 'matic' | 'optimism';
  // The token address of this token (called mint address for solana).
  tokenAddress: string;
  // The number of decimals this token has.
  decimals: number;
  symbol?: string;
  // token name
  name?: string;
  // url of the image for token logo
  logo?: string;
}

interface ConversionEventMetadata {
  // token metadata for multiple token support
  // To be sent with each event if campaign supports multiple tokens
  // otherwise default campaign token will be used
  conversion?: {
    tokenMetadata?: TokenSpec;
  };
  // To be sent with each event if campaign supports multiple tokens
  // otherwise default campaign token will be used
  revenue?: {
    tokenMetadata?: TokenSpec;
  };
}

interface ConversionEvent {
  // event name to uniquely identify conversion event
  eventName: string;
  // public wallet address of the invitee
  inviteePublicKey: string;
  // The referral code associated with invitee
  referralCode?: string;
  // revenue value driven by invitee
  revenueValue?: number;
  // conversion value driven by invitee
  conversionValue?: number;
  // Conversion event metadata
  metadata?: ConversionEventMetadata;
}

Sample cURL

curl --location 'https://us-central1-qwestive-referral-prod.cloudfunctions.net/setConversionEvents' \
--header 'Content-Type: application/json' \
--data '{
   "secretApiKey": "/h8+oOoasQJ7zcqKMkyzA0QD9xpNdE7xxiflPzfy0Bs=",
  "projectId": "testingProject1234",
  "campaignId": "testCampaignId2",
  "events": [
    {
      "eventName": "PLAY_GAME",
      "inviteePublicKey": "InviteeNRooBzvZ1WB3UJvQqM8R2CiGcaaEREXMg123",
      "revenueValue": 10
    },
    {
      "eventName": "PLAY_GAME",
      "inviteePublicKey": "InviteeNRooBzvZ1WB3UJvQqM8R2CiGcaaEREXMg123",
      "revenueValue": 30
    },
    {
      "eventName": "PLAY_GAME",
      "inviteePublicKey": "InviteeNRooBzvZ1WB3UJvQqM8R2CiGcaaEREXMg124",
      "revenueValue": 10,
      "conversionValue": 10
    },
    {
      "eventName": "PLAY_GAME",
      "inviteePublicKey": "InviteeNRooBzvZ1WB3UJvQqM8R2CiGcaaEREXMg125",
      "conversionValue": 5
    }
  ]
}'

Please contact us for setting up eventName as conversion event identifier.

FAQs

What is conversionValue?

Conversion value is a metric that is used for tracking campaign performance. We can provide any value that is considered important, we will aggregate that value and provide it per invitee/per referrer/per date and if there is any threshold defined in the campaign settings, we would compare the aggregated conversionValue against that to mark the registered invitee as converted and become eligible for rewards.

What is revenueValue?

Revenue value is another metric that is used for tracking campaign performance. We can provide any value that represents the revenue that we would be making from a user's conversion event.

For example, an invited user swaps 500$ on your Dapp and conversionThreshold was set to 500$ for the campaign and Dapp makes 5$ revenue out of that transaction. We can send below event to setConversionEvents API and it would mark the invited user as converted user along with updating total conversionValue, revenueValue for the campaign:

{
  "eventName": "SWAP_TOKEN",
  "inviteePublicKey": "InviteeNRooBzvZ1WB3UJvQqM8R2CiGcaaEREXMg124",
  "revenueValue": 5,
  "conversionValue": 500
}