Documentation
Integration
Referral Integration

Integrate a Referral Widget

This guide will walk you through the process of installing and integrating the referral widget into your application. You can integrate a campaign using two ways, either by using our react SDK or by using our widget CDN script.

Using React SDK

Step 1: Installation

Run the following command in your terminal to install the package:

This will add the @bandit-network/react package to your project dependencies.

Step 2: Integration

After installing the package, you can now import the necessary components from it. Specifically, you will need the BanditContextProvider and Referral components.

Here's how you can import them:

import { BanditContextProvider, Referral } from "@bandit-network/react";

Now, you can use these components in your application. The BanditContextProvider component is a context provider that makes the Bandit Network API available to your application. It requires an apiKey and a cluster as props.

The Referral component is the referral widget itself. It requires an id prop, which should be the ID of the referral campaign that you want to display.

Here's an example of how you can use these components:

const App = () => {
  return (
    <BanditContextProvider
      apiKey="REPLACE_WITH_API_KEY"
      cluster="mainnet"
    >
      <Referral campaignId="REPLACE_WITH_CAMPAIGN_ID" />
    </BanditContextProvider>
  );
};

In this example, replace REPLACE_WITH_CAMPAIGN_ID with your referral campaign ID and replace REPLACE_WITH_API_KEY with your API key.

Custom Referral Link Generation

You can also generate a custom referral link using the SDK, which looks like this:

https://yourwebsite.com/?referral_code=REFERRRAL_CODE

This github repository (opens in a new tab) contains the code for the referral widget and the custom referral link generation, which you can use as a reference to integrate the referral widget into your application with custom referral link generation.

Testing Your Integration

When integrating the Bandit Network campaign widget, it's crucial to test your implementation before deploying to production. We provide two environments for testing and production use.

Environments

  1. Devnet (Test Environment)

    • Cluster: 'devnet'
    • Use this for development and testing purposes.

  2. Mainnet (Production Environment)

    • Cluster: 'mainnet'
    • Use this for your live, production application.

API Reference

The Referral component and mountReferral function accept the following props:

campaignId

The ID of the referral campaign you want to display.

  • Type: number

cluster

The environment cluster you want to connect to.

  • Type: string
  • Options: 'mainnet', 'devnet'

displayMode (optional)

Specifies how the campaign should be presented, either embedded inside the website or in a modal.

  • Type: string
  • Options: 'modal', 'integrated'
  • Default: 'integrated'

isOpen (optional)

If the displayMode is set to 'modal', isOpen controls the visibility of the referral campaign modal.

  • Type: boolean
  • Default: false

onClose (optional)

If the displayMode is set to 'modal', onClose will be triggered once the modal is closed.

  • Type: function

referralCodePrefixUrl (optional)

Specify a base URL that will be prefixed to the referral code when generating referral links.

  • Type: string

defaultReferralCode (optional)

The referral code can be provided to automatically populate the input field for entering a friend's referral code.

  • Type: boolean

displayCodeGeneration (optional)

Hides the code generation section on the widget.

  • Type: boolean
  • Default: false

displaySubmitFriendCode (optional)

Hides the submit friends referral code section on the widget.

  • Type: boolean
  • Default: false

displayStats (optional)

Hides the statistics section on the widget.

  • Type: boolean
  • Default: false

render (optional)

Allows you to render your own UI. The render function provides the necessary arguments ReferralRenderArgsType.

  • Type: function
Campaign IntegrationLeaderboard Integration