GameShift Loyalty Rewards User Guide

The GameShift Loyalty Rewards feature allows you to reward players for holding game assets and engaging with your game. With a flexible rewards calculation infrastructure, our feature allows you to design programs perfectly suited to incentivize the player behavior you desire. Players can register for one of your loyalty programs by committing some amount of your game token for a period of time. You can choose to reward your players at any time, proportional to their committed tokens. However, they can only withdraw their rewards once their commitment period expires. If they wish to withdraw their committed tokens before the end of their commitment period, they will have to leave behind any rewards issued to them.

GameShift Loyalty Rewards is live on devnet, and currently in progress of being audited before our mainnet launch. In addition to our flexible program design and custom on-chain program, our API allows you to manage your loyalty programs and user data without having to build and maintain your own indexers and program SDKs.

Overview

Prerequisites

1. Import an SPL token into your GameShift game

You must have an SPL token registered for your project that is used in your game.

2. Ensure you are offering game-related utility with your token and your program design.

Users of this feature must connect reward logic and the use of the token to player interaction with your game.

3. Register a developer wallet

You can set up a developer wallet for your project in your project's GameShift portal. When you create a rewards program, you will provide your wallet secret for your developer wallet. Only your GameShift developer wallet can change the program after it is created.

Steps

1. Create your first create your Loyalty Program
2. Enroll users in the program
3. Fund your Rewards program with your Currency
4. Create a Rewards Snapshot
5. Publish your Rewards using your Developer Wallet
6. Allow players to claim their rewards after their commitment period has expired
7. Allow players to disenroll from your program and withdraw their committed token balance

Player Enrollment States

Each player can have multiple enrollments. An enrollment represents a single quantity of tokens committed by the player at a single time, with a particular time commitment. Players are allowed to enroll in your program as long as the total number of tokens and total number of enrollments do not exceed the limits you specify when you create the program, and as long as the program remains open. You can close a program to new enrollments using the update endpoint.

Create a Program

You can create one or more rewards programs. You will use our API to configure the reward program. Each program specifies:

• The game token that will be used by players to enroll in the program and to reward players
• The maximum number of enrollees allowed in the program, and the maximum number of tokens that may be enrolled at any given time
• The minimum and maximum enrollment period that an enrollee can choose to commit their tokens to the program. When you enroll users, you can enforce custom logic for what enrollment periods are valid (e.g. 30 days, 60 days, etc). Right now, the maximum allowed commitment period is currently 120 days.

Note that program creation incurs a small cost to create on-chain accounts to hold program data, which must be paid by funding your developer wallet with SOL tokens.

Joining a Rewards Program

You will publish to players the various programs and enrollment options. For each program, you can specify any number enrollment options with combinations of token amounts and commitment periods that fit within the limits you used when creating the program. For example, you might create a new program with a valid commitment range of 30-100 days, maximum tokens of 100,000, and maximum enrollees of 500. Then you might publish these options on your game for players to select from:

• Enroll 500 tokens for 30 days and get a 1.2x reward boost
• Enroll for 90 days to get a 1.7x reward boost
• Enroll more than 2,500 tokens to get a 2x reward boost

When a player wishes to enroll in a rewards program, you will call the Enroll GameShift API to generate a consent flow that the player will approve in order to enroll in the program.

You will specify:

• User referenceID
• Number of currency tokens to enroll
• Enrollment commitment period, in days. Note that the maximum allowed commitment period is currently 120 days.
• Rewards program ID

This API will return a consent URL for the user to approve the transaction. Upon approval, the user’s tokens will be transferred from their wallet to the rewards program on chain, and they will be officially enrolled in the program.

Users can enroll in a rewards program multiple times, and each enrollment will be tracked and managed separately as an “Enrollment Account” with an Enrollment Account ID. You can retrieve the status of a user’s rewards enrollments with Get Enrollments, which will return a list of Enrollment Accounts for the user. Each Enrollment Account will include relevant information such as the enrollment time, the commitment period, commitment period remaining, enrolled balance, the rewards program it is associated with, and unwithdrawn accrued rewards.

You can also get a paginated list of all Enrollment Accounts across all users.

Note that it is technically possible - though difficult - for anyone to enroll in your rewards program without the involvement of you or GameShift by creating and submitting their own enrollment transaction. In this case, GameShift will automatically associate the enrollment to a user reference ID if the address that signs the transaction has previously been registered by your game. If this association is unsuccessful, the user reference ID returned by this endpoint will be null. Users that choose to interact with the program on-chain will do so at their own risk.

Revising the Program

While the program is open, you can update the following parameters:

• Allow/disallow new enrollees. This is useful for managing the size of your programs

You can close the program at any time via the Update Program endpoint. Closing the program simply means that all players will be immediately eligible to withdraw their game currency balance from the program, including any accrued but unwithdrawn rewards.

Rewards

Funding Rewards

Periodically, you will fund the reward program by calling the Fund API with your developer wallet secret. Your developer wallet must hold enough game tokens to complete the funding request. Any tokens funded to the program will be recorded as unallocated rewards, not attributable to any enrollee, until you call our API to allocate rewards to the users enrolled in the programs.

Allocating Rewards

In order to allocate rewards to enrollees, we require you to provide a set of multipliers. The multipliers are combined with Enrollment Account token amounts to determine each Account’s relative share of the unallocated rewards pool. This means that if you provide a multiplier of 1.0 for every Enrollment Account, the unallocated rewards pool will be distributed across the Enrollment Accounts solely based on each Account’s enrolled token amount. Conversely, you can use any logic you desire to calculate the multipliers. Some possibilities include:

• Multiplier boosts for longer enrollment periods or larger commitment amounts
• Boosts or reductions based on in-game activity
• Boosts for interacting with your social media accounts
• Boosts for achievements in game

When you want to allocate rewards, you will call two APIs. First, you call Create Rewards Snapshot to send in the desired allocation multipliers. After processing is complete, you may then call Publish Rewards to process the rewards on-chain.

Our Rewards endpoint accepts a list of enrollment IDs and a multiplier for each. Our API will compute each Enrollment Account’s amount of unallocated rewards relative to the total weight of all enrollments using this formula

enrollment_reward_allocation[i] = (
 enrolled_token_amounts[i] * multipliers[i]
) / sum([locked_token * multiplier for zip(enrolled_token_amounts, multipliers)])

For the visually inclined, the rewards for enrollment account i is this:

Disenrollment & Claiming Rewards

There are three ways users can disenroll from programs

In all cases, you will use our disenrollment and rewards claim endpoints to receive a consent URL which the user must visit to approve the on-chain transaction that retrieves their rewards or their enrolled tokens.

Scenario 1: Early Disenrollment

If the player wishes to disenroll before their commitment period has elapsed, you will call our disenroll endpoint with the disenrollWithoutClaiming flag. This will return their earned but unclaimed rewards to the unallocated rewards pool.

Scenario 2: Forfeit Rewards and Disenroll

If the player is eligible to withdraw rewards but prefers to forfeit them, follow the steps for Scenario 1.

Scenario 3: Normal Disenrollment

Players that have elapsed their commitment period must make two transactions. First, you will call our claim rewards endpoint with the amount of rewards to claim. You can confirm that transaction completes by using our webhooks or by checking the transaction status. After the transaction completes, you will call our disenroll endpoint without the disenrollWithoutClaiming flag in order to avoid accidentally forfeiting any remaining rewards.

Statistics and Other APIs

At any time you can call the following endpoints to retrieve information about your rewards programs:

• Get loyalty program stats
• Get all loyalty programs
• Get all enrollments in a program
• Get rewards snapshots to view the history of how rewards have been allocated

You can also subscribe to webhooks notifications for activity on the program via the GameShift Dashboard, including:

• Enrollments
• Disenrollments
• Reward claims
• Rewards allocation