Referral program

How it works

A referral program is a tool designed to attract new users, when existing users invite others via a referral link. The program can be integrated into a website or a game. As a result, all program participants receive rewards:

• The invitee receives a reward only once, after making the first purchase.
• The inviting user receives a reward for each invitee who has made a purchase in the store.

• any website, including ones created using Xsolla site builder
• a game

Regardless of where the referral program is used – on a website or in a game – its mechanics and reward conditions remain the same.

Referral program configuration is available for the following scenarios:

• selling in-game items — virtual items, virtual currency packages, and bundles
• selling games and DLC via game keys

• Providing one or several items of the following types as a reward:
  • virtual currency
  • virtual item
  • bundle with items
• Customization of the referral program widget.
• Generation of referral links.
• Ability for a user to change the referral program before making their first purchase.

• There can only be one referral program in the project.
• Users can’t invite themselves.

User flows

Inviting user flow

1. The user logs in or registers on the site or in the game.
2. The user opens the referral program widget and reads the program conditions.
3. The user gets the referral link in the widget.
4. The user shares the referral link with another user.
5. The user opens the referral program widget and receives a reward if the invitee followed the referral link and fulfilled the program conditions.

Invitee flow

1. The user receives a referral link with a description of the program conditions and rewards.
2. The user follows the referral link.
3. The user registers on the website or in the game.
4. The user makes the first purchase.
5. The user receives the reward.

How to set up

Create referral program

1. Open your project in Publisher Account and go to the LiveOps > Referral program section.

2. Click Create referral program.
3. Set the necessary parameters:
   • Specify the referral program name.
   • Enter the description.

4. Click Next.
5. Add rewards that users will receive:

• To add a reward for the inviting user, in the Reward for inviting players section, specify the item SKUs and their quantity.

• To add a reward for the invitees, in the Reward for invitees section, specify the items SKUs and their quantity.

6. Click Next.
7. Review the settings of the referral program and click Create.

Edit referral program

You can make changes to the active referral program:

• change the list of items that are provided as rewards
• change conditions

1. Go to the created referral program.
2. Click Edit.

3. Update text and/or users item list.
4. Click Next.
5. Review the referral program settings and click Create.

The edited referral program is enabled by default and is displayed in the Referral program section. After you save the changes, users will see the updated program conditions and receive new rewards.

Rewards that users have already received before the conditions update will not change.

Re-publishing the widget is not required after updating the conditions.

How to display

The referral program is displayed via a widget. To allow users to view the program conditions and participate, add the widget to your website or the game.

Set up widget

1. On the created referral program page, click Go to customizer.

2. Set up widget components for each state. To make the widget match the design of the game and site, you can customize it and configure the following features:
   • a set of UI elements
   • colors of UI elements
   • button texts and headers including localization
   • font type, color, and size

3. Set up localization. All widget texts are translated into the project languages specified in Publisher Account in the Project settings > General settings > Project languages section. To change the default translations, click on the text twice and enter your own text.
4. Publish the changes
5. Copy the widget code in the opened window and add it to your website.

After publishing the widget you can always return to the widget settings and make changes. To apply the changes, re-publish the widget.

Add widget code to your site via Xsolla site builder

If you implement your own site interface, add the widget code into your site’s code. If you use Xsolla site builder, follow the steps to add a referral program widget to your site:

1. Open your project in Publisher Account and go to the Storefronts > Websites section.
2. In the Sites section, select your site and click Open Site Builder.
3. Click Add Block.
4. Select the Custom code block.
5. Add the referral program widget code.
6. To apply the changes, publish the website:

1. 1. In the upper-right corner of the Site Builder click Publish.

1. 2. Select the checkboxes next to the pages you want to publish.

1. 3. Confirm that the website is ready for publishing and click Publish.

Integrate into game or your own site

To integrate the referral program into a game or a website created without Xsolla site builder, follow these steps:

1. Implement user authentication in the widget on your side. User authentication in the referral program widget is performed through authentication on the website where the widget is embedded. There are 2 user authentication scenarios — on the website or in the widget:

1. • If the user logs into the site, you need to pass the user’s authorization token to the widget using the onTokenChange() method. When the user logs out of the system, pass null as the method parameter.

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
    participant User as User
    participant WebShop as Web Shop
    participant Widget as Widget
    User ->> WebShop: Login
    activate WebShop
    WebShop ->> Widget: Notification with token
    deactivate WebShop

1. • If the user logs in through the widget, the widget will call the requestAuth function passed to it during initialization. In response, the site should return the user’s authorization token.

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
    participant User as User
    participant WebShop as Web Shop
    participant Widget as Widget
    User ->> Widget: Login
    activate Widget
    Widget ->> WebShop: Login request
    deactivate Widget
    activate WebShop
    WebShop ->> Widget: token
    deactivate WebShop

Example code for initializing the widget:

1window.XESApi.init({
2requestAuth: requestAuth,
3token: getToken()
4})

2. Ensure that referral data is passed correctly.
3. Embed the referral program widget code into the game or website interface.

Widget API

The widget API provides a set of functions and methods for authenticating a user in the widget:

Widget states

The referral program widget can have different states depending on the type of user (inviting or invitee), user’s authorization status, and fulfillment of program conditions.

The set of widget components includes UI elements for different states. You can configure components when setting up the widget.

Button to open the widget:

State	Description	Who it’s displayed to	Components that can be edited	Image
View details	Engaging the user to participate in the program.	Authorized users who are not yet participating in the program.	Background and text colours. Text of the widget open button and view details button text.
Waiting for authorization	Encouraging the user to log in through the widget.	Unauthorised users who have followed the referral link.	Background and text colours. Button texts.
Waiting for the first purchase	Encouraging the user to make the first purchase.	Users who have followed the referral link and logged in to the site.	Background and text colours. Button texts.
Receiving a reward	Encouraging the user to receive a reward.	Inviting users whose friends have met the program conditions, and they can receive a reward.	Background and text colours. Button texts.
Closing the widget	The widget is open, the button is displayed as the × icon.	Authorized users who have opened the widget details.	Background and text colours. Button colour.
Default	The widget is closed.	Users who have closed the widget.	Background and text colours. Button text.

Widget page for the inviting user:

Description	Who it’s displayed to	Components that can be edited	Image
Referral program details. Button for sending the referral link. List of rewards with statuses: Claimed — reward for the invitee has been received. In progress — invitee has logged in to the site, but has not yet made a purchase. Claim — invitee has logged in to the site and made the first purchase. The inviting user can receive a reward.	An authorized inviting user, whose friend followed the referral link and logged in to the site.	Background and text colours. Widget text, button texts.
FAQ section	An authorized inviting user who clicked the program information button.	Adding and removing blocks with questions. Background and text colors. Content of questions and answers.

Widget page for the invitee:

Description	Who it’s displayed to	Components that can be edited	Image
The widget text encourages to make a purchase on the site. After making a purchase, the user is shown a notification about receiving a bonus.	Users who have followed the referral link and logged in.	Background and text colors. Widget text, button texts.