Implementation Best Practices

Implementation Example Using the Conversion API

1. Retrieve the Referral ID from the Referral Link

When an affiliate joins a project on Qube, a unique referral link is generated for them. This link is used to promote the project, allowing new users to access the client’s product through the referral link.

To track which affiliate's link was used, the link includes an r parameter, which serves as the referral ID. Additionally, if the access is made via an external ASP integrated with Qube, a click_id parameter is also appended to the link.

Both the referral ID and click ID are required when calling the Conversion API, so they must be accurately retrieved and stored. In particular, for conversions that occur through an ASP, the click_id is mandatory. Therefore, it is essential to properly store the click_id received during redirection.

• Example of a Referral Link

  A link like the following will be generated:

  https://example.com?r=<Referral ID>&click_id=<click_id>

  • r (Referral ID): An ID used to identify which affiliate's link was used.

  • click_id (Click ID): An ID assigned when the access is made via an ASP (not present if the access is not through an ASP).

Below is an implementation example for retrieving the Referral ID and Click ID.

Implementation Example

• Next.js:

  import { useRouter } from "next/router";
  import { useEffect, useState } from "react";
  
  const NFTPurchasePage = () => {
    const router = useRouter();
    const [referralID, setReferralID] = useState<string | null>(null);
    const [clickID, setClickID] = useState<string | null>(null);
  
    useEffect(() => {
      const { r, click_id } = router.query;
      if (r) {
        setReferralID(r as string);
      }
      if (click_id) {
        setClickID(click_id as string);
      }
    }, [router.query]);
  
    return (
      <div>
        <h1>NFT Purchase Page</h1>
        {referralID && <p>Referral ID: {referralID}</p>}
        {clickID && <p>Click ID: {clickID}</p>}
      </div>
    );
  };
  
  export default NFTPurchasePage;

• Python (Flask):

  from flask import Flask, request
  
  app = Flask(__name__)
  
  @app.route("/nft_purchase")
  def nft_purchase():
      referral_id = request.args.get("r")
      click_id = request.args.get("click_id")
  
      response = f"Referral ID: {referral_id}" if referral_id else "No Referral ID provided"
      response += f"<br>Click ID: {click_id}" if click_id else "<br>No Click ID provided"
  
      return response
  
  if __name__ == "__main__":
      app.run(debug=True)

• Node.js (Express):

  const express = require("express");
  const app = express();
  
  app.get("/nft_purchase", (req, res) => {
    const referralID = req.query.r;
    const clickID = req.query.click_id;
  
    let response = referralID ? `Referral ID: ${referralID}` : "No Referral ID provided";
    response += clickID ? `<br>Click ID: ${clickID}` : "<br>No Click ID provided";
  
    res.send(response);
  });
  
  app.listen(3000, () => {
    console.log("Server running on port 3000");
  });

2. Saving the Referral ID

The retrieved referral ID (and Click ID) should be stored in the client's product database along with the user's information (e.g., user ID, email address, etc.). This stored data will be required when calling the Qube Conversion API later.

• Why is it necessary to save the referral ID?

  When a user performs a specific action in the client product (e.g., making a purchase or registering), and this action is detected as a conversion, it is necessary to notify Qube about which affiliate's link was used. The referral ID (and Click ID) is required for this notification.

• Purpose of Saving

  • To determine which affiliate's link the user utilized during a conversion.

  • To properly use the referral ID (and Click ID) when calling the Conversion API.

• Important Points

  • It is not mandatory to associate the referral ID with a "user ID." Any information that can uniquely identify the user (e.g., email address or wallet address) is sufficient.

  • Ensure that the stored data is managed in a way that allows the referral ID (and Click ID) to be easily retrieved when calling the Conversion API.

Below is an implementation example.

Implementation Example

• Next.js (Firebase):

  import firebase from "firebase/app";
  import "firebase/firestore";
  
  const db = firebase.firestore();
  
  /**
   * Saves referral and click ID data to Firestore.
   * @param {string} referralID - The referral ID from the URL parameters.
   * @param {string} userID - The user ID of the registered user.
   * @param {string | undefined} clickID - The click ID from the URL parameters (if available).
   */
  const saveReferralData = async (referralID: string, userID: string, clickID?: string) => {
    try {
      await db.collection("referrals").add({
        referralID,
        clickID: clickID || null, // Store as null if undefined
        userID,
        timestamp: firebase.firestore.FieldValue.serverTimestamp(),
      });
      console.log("Referral data saved successfully");
    } catch (error) {
      console.error("Error saving referral data: ", error);
    }
  };

• Python (Flask + PostgreSQL):

  from flask import Flask, request, jsonify
  from flask_sqlalchemy import SQLAlchemy
  
  app = Flask(__name__)
  app.config["SQLALCHEMY_DATABASE_URI"] = "postgresql://username:password@localhost/dbname"
  db = SQLAlchemy(app)
  
  class Referral(db.Model):
      id = db.Column(db.Integer, primary_key=True)
      referral_id = db.Column(db.String(80), nullable=False)
      click_id = db.Column(db.String(80), nullable=True)  # Allow NULL values
      user_id = db.Column(db.String(120), nullable=False)
  
  @app.route("/save_referral", methods=["POST"])
  def save_referral():
      data = request.json
      referral_id = data.get("referralID")
      user_id = data.get("userID")
      click_id = data.get("clickID")  # Optional parameter
  
      if not referral_id or not user_id:
          return jsonify({"error": "Missing required parameters"}), 400
  
      new_referral = Referral(referral_id=referral_id, click_id=click_id, user_id=user_id)
      db.session.add(new_referral)
      db.session.commit()
  
      return jsonify({"message": "Referral data saved successfully"}), 201
  
  if __name__ == "__main__":
      app.run(debug=True)

• Node.js (Express + MongoDB):

  const mongoose = require("mongoose");
  
  // Define the schema with clickID as an optional field
  const referralSchema = new mongoose.Schema({
    referralID: { type: String, required: true },
    userID: { type: String, required: true },
    clickID: { type: String, default: null }, // Optional clickID
    timestamp: { type: Date, default: Date.now },
  });
  
  const Referral = mongoose.model("Referral", referralSchema);
  
  const saveReferralData = async (referralID, userID, clickID = null) => {
    try {
      const newReferral = new Referral({ referralID, userID, clickID });
      await newReferral.save();
      console.log("Referral data saved successfully");
    } catch (error) {
      console.error("Error saving referral data: ", error);
    }
  };
  
  module.exports = saveReferralData;

3. Calling the Conversion API

When a user completes a specific action (e.g., a purchase or registration), use the saved referral ID (and Click ID) to call Qube's Conversion API. This API call allows Qube to record the conversion and calculate appropriate rewards for the affiliate.

• When to Call the Conversion API

  The Conversion API should be called at the moment the "conversion condition" defined within the client product is met. These conditions may be based on actions such as:

  • Completing a product purchase.

  • Completing a new user registration.

  • Clicking a specific button.

  The client must evaluate these conditions within their product and call the API when a conversion is successfully detected.

• Required Data

  Refer to this document for details.

• Implementation Tips

  • Ensure the request header includes the API key issued for the project. Without this key, the API authentication will fail.

  • The Conversion API operates based on the project's configuration. For example, the required request data may vary depending on whether the reward type is FixedAmount or RevenueShare. (See details)

Implementation Example

• Next.js (Firebase):

  const handleConversionComplete = async (
    referralId: string,
    conversionId: string,
    revenue?: number,
    userWalletAddress?: string,
    clickId?: string
  ) => {
    try {
      const requestBody: Record<string, any> = {
        referralId,
        conversionId,
      };
  
      if (revenue !== undefined) {
        requestBody.revenue = revenue;
      }
  
      if (userWalletAddress) {
        requestBody.userWalletAddress = userWalletAddress;
      }
  
      if (clickId) {
        requestBody.click_id = clickId;
      }
  
      const response = await fetch(
        `https://staging-qube.vercel.app/api/v1/conversion`,
        {
          method: "POST",
          headers: {
            "x-api-key": "YOUR_API_KEY_HERE",
            "Content-Type": "application/json",
          },
          body: JSON.stringify(requestBody),
        }
      );
  
      if (response.ok) {
        console.log("Conversion successful");
      } else {
        console.error("Conversion failed:", await response.json());
      }
    } catch (error) {
      console.error("Error calling conversion API:", error);
    }
  };

• Python (Flask + Requests):

  import requests
  
  def call_conversion_api(referral_id, conversion_id, revenue=None, user_wallet_address=None, click_id=None):
      url = "https://staging-qube.vercel.app/api/v1/conversion"
      headers = {
          "x-api-key": "YOUR_API_KEY_HERE",
          "Content-Type": "application/json"
      }
      payload = {
          "referralId": referral_id,
          "conversionId": conversion_id
      }
      
      if revenue is not None:
          payload["revenue"] = revenue
      if user_wallet_address:
          payload["userWalletAddress"] = user_wallet_address
      if click_id:
          payload["click_id"] = click_id
  
      try:
          response = requests.post(url, headers=headers, json=payload)
          if response.status_code == 200:
              print("Conversion successful")
          else:
              print("Conversion failed:", response.json())
      except Exception as e:
          print("Error calling conversion API:", str(e))
  

• Node.js (Express + Fetch):

  const fetch = require("node-fetch");
  
  const callConversionAPI = async (
    referralId,
    conversionId,
    revenue,
    userWalletAddress,
    clickId
  ) => {
    try {
      const payload = {
        referralId,
        conversionId,
        ...(revenue !== undefined && { revenue }),
        ...(userWalletAddress && { userWalletAddress }),
        ...(clickId && { click_id: clickId })
      };
  
      const response = await fetch(
        "https://staging-qube.vercel.app/api/v1/conversion",
        {
          method: "POST",
          headers: {
            "x-api-key": "YOUR_API_KEY_HERE",
            "Content-Type": "application/json",
          },
          body: JSON.stringify(payload),
        }
      );
  
      if (response.ok) {
        console.log("Conversion successful");
      } else {
        const errorData = await response.json();
        console.error("Conversion failed:", errorData);
      }
    } catch (error) {
      console.error("Error calling conversion API:", error);
    }
  };

4. Data Management

Once a conversion is completed, it is essential to properly delete records linking the referral ID and the user to prevent duplicate reward payments for the same conversion. Failing to handle this process can lead to risks such as unauthorized access or duplicate actions resulting in duplicate reward payouts.

• Note: Risk of Duplicate Conversions

  For example, if a specific action in a game (e.g., defeating a boss or purchasing an item) triggers a conversion, the following scenarios could occur:

  1. A user performs the action, exits the game, and repeats the same action multiple times using the same referral ID.

  2. Each time the action is detected, the same referral ID is retrieved from the database, resulting in multiple reward payouts.

  To prevent such abuse, it is necessary to remove the referral ID from the database before calling the Conversion API, ensuring that the same referral ID cannot be used multiple times.

• Solution: Best Practices

  1. Simultaneous Retrieval and Deletion of Referral ID

     • Before calling the Conversion API, first retrieve the referral ID from the database and store it in a variable. Immediately after, delete the corresponding record. This process ensures that the same referral ID cannot be used multiple times.

  2. Use Transactions

     • What is a Transaction?

       A transaction is a mechanism that groups a series of operations into a single execution. In a transaction, all operations either succeed or fail together. For instance, if the process of retrieving and deleting a referral ID is performed within a transaction, any error that occurs will prevent the operation from being left incomplete. Using transactions ensures data consistency and safe execution of operations.

     • Execute the retrieval and deletion of the referral ID as part of a single transaction to avoid conflicts or inconsistencies during concurrent access. Transactions minimize the risk of another process accessing the same data before the referral ID is deleted.

  3. Error Handling Based on the Conversion API Response

     • If the Conversion API call fails, there is no need to restore the deleted referral ID back into the database. This prevents the reuse of the same referral ID.

  4. Implementing Restrictions Within the Client Product

     To prevent users from performing specific actions (e.g., defeating a boss, purchasing an item) multiple times, implement appropriate restrictions within the client product.

     Here are some possible approaches:

     • Managing Action History

       Record each user's action history in the database and disable repeated execution if the same action has already been logged.

       if (actionAlreadyCompletedByUser(userId, actionId)) {
         throw new Error("This action cannot be completed multiple times.");
       }

     • Setting Cooldowns for Actions

       Use timestamps to manage cooldown periods, ensuring that specific actions cannot be executed again within a set time frame.

       if (timeSinceLastAction(userId, actionId) < cooldownPeriod) {
         throw new Error("Action is currently on cooldown.");
       }

     • Tracking State

       Restrict actions based on the user's progress, such as preventing actions if a boss has already been defeated or an item has been purchased.

       if (isBossAlreadyDefeated(userId, bossId)) {
         throw new Error("This boss has already been defeated.");
       }

This approach helps prevent the misuse of specific actions on the client side while further reducing the risk of duplicate referral ID usage when calling the Conversion API on the Qube side.

Implementation Example

• Firebase:

  import firebase from "firebase/app";
  import "firebase/firestore";
  
  const handleConversion = async (userID: string, conversionId: string) => {
    const db = firebase.firestore();
  
    try {
      // Retrieve and Delete the Referral ID Within a Transaction
      const referralID = await db.runTransaction(async (transaction) => {
        const querySnapshot = await db
          .collection("referrals")
          .where("userID", "==", userID)
          .get();
  
        if (querySnapshot.empty) {
          throw new Error("Referral ID not found for user");
        }
  
        const referralDoc = querySnapshot.docs[0];
        const referralData = referralDoc.data().referralID;
  
        // Delete the Referral ID
        transaction.delete(referralDoc.ref);
        return referralData;
      });
  
      // Call the Conversion API
      const response = await fetch(
        "<https://staging-qube.vercel.app/api/v1/conversion>",
        {
          method: "POST",
          headers: {
            "x-api-key": "YOUR_API_KEY_HERE",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            referralId: referralID,
            conversionId: conversionId,
          }),
        }
      );
  
      if (response.ok) {
        console.log("Conversion successful");
      } else {
        console.error("Conversion failed:", await response.json());
      }
    } catch (error) {
      console.error("Error processing conversion:", error);
    }
  };

• MongoDB:

  const mongoose = require("mongoose");
  const fetch = require("node-fetch");
  
  const handleConversion = async (userID, conversionId) => {
    const Referral = mongoose.model("Referral");
  
    try {
      const session = await mongoose.startSession();
      session.startTransaction();
  
      // Retrieve and Delete the Referral ID
      const referralData = await Referral.findOneAndDelete(
        { userID },
        { session }
      );
      if (!referralData) {
        throw new Error("Referral ID not found for user");
      }
      const referralID = referralData.referralID;
  
      // End the Transaction
      await session.commitTransaction();
      session.endSession();
  
      // Call the Conversion API
      const response = await fetch(
        "<https://staging-qube.vercel.app/api/v1/conversion>",
        {
          method: "POST",
          headers: {
            "x-api-key": "YOUR_API_KEY_HERE",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            referralId: referralID,
            conversionId: conversionId,
          }),
        }
      );
  
      if (response.ok) {
        console.log("Conversion successful");
      } else {
        const errorData = await response.json();
        console.error("Conversion failed:", errorData);
      }
    } catch (error) {
      console.error("Error processing conversion:", error);
    }
  };

Specific Example of Data Flow: Scenario with Affiliates A, B, and Users A, B, C

[Assumptions]

• Affiliate A: Referral Link A (referralA)

• Affiliate B: Referral Link B (referralB)

• Users: userA, userB, userC

[Database Structure]

• Referral Table (referrals)

  userId	referralId	createdAt
  (Empty)	(Empty)	(Empty)

• Conversion Log Table (conversions)

  userId	referralId	conversionId	createdAt
  (Empty)	(Empty)	(Empty)	(Empty)

[Chronological Data Flow]

Timestamp	Event	State of Referral Table	State of Conversion Log Table
2024-11-20 10:00:00	User A accesses via Referral Link A	[(userA / referralA / 2024-11-20 10:00:00)]	(Empty)
2024-11-20 10:05:00	User B accesses via Referral Link B	[(userA / referralA / 2024-11-20 10:00:00), (userB / referralB / 2024-11-20 10:05:00)]	(Empty)
2024-11-20 10:10:00	User C accesses via Referral Link A	[(userA / referralA / 2024-11-20 10:00:00), (userB / referralB / 2024-11-20 10:05:00), (userC / referralA / 2024-11-20 10:10:00)]	(Empty)
2024-11-20 10:20:00	User A triggers a conversion	[(userB / referralB / 2024-11-20 10:05:00), (userC / referralA / 2024-11-20 10:10:00)]	[(userA / referralA / conv001 / 2024-11-20 10:20:00)]
2024-11-20 10:30:00	User C triggers a conversion	[(userB / referralB / 2024-11-20 10:05:00)]	[(userA / referralA / conv001 / 2024-11-20 10:20:00), (userC / referralA / conv002 / 2024-11-20 10:30:00)]

Explanation

1. Access Events:

   • Each time a user clicks on a referral link, the referrals table stores the userId and referralId.

   • Even when handling multiple affiliates or referral links, data is individually stored for each user during every access.

2. Conversion Events:

   • When a conversion occurs, the following processes are executed:

     • Referral Table: The corresponding userId entry is deleted.

     • Conversion Log Table: A new entry is created with userId, referralId, and conversionId.

       Note:

       This conversion log table is an example created to clarify the data flow. In practice, Qube automatically records conversion data, so the client product does not need to store conversion logs. However, managing referral IDs and user information to pass data to Qube is necessary.

3. Issues Prevented:

   • Since the referral ID is deleted during the Conversion API call, misuse due to duplicate use of the same referral ID is prevented.