Upsight logo Back to top

Rewards

Overview

What are Rewards?

Rewards are items you define that are given to your users using the Reward Campaigns. Any creative can contain a reward for your user.

In order to set up a reward, first add Reward items to your app settings in the dashboard before creating a Reward Campaign.

Important Please note that the Reward item that you define on the Upsight dashboard will be converted to lower case and can only contain alphanumeric characters and underscores.

Reward Use Cases

  • Improve Retention with Daily or Weekly Login Rewards

  • Create Regional Specific Item Promotions

  • Reengage Inactive Users

  • Establish Better Relationships with Top Users

How to add a Reward

  1. To add a Reward, navigate to APPLICATIONS > APP NAME > APP SETTINGS > REWARDS > ADD REWARD.

  2. In the TAG textbox, enter the name you would like to use for your reward item.

    Note This should be a unique string that represents unlockable content in your app and must be recognized within your app code.

  3. In the DESCRIPTION textbox, enter a more detailed description of your reward.

  4. For SUPPORTED APP VERSIONS, select the min and max versions that the reward is supported for your app.

  5. Then click SAVE to add the Reward to the dashboard.

Note Reward campaigns require additional instrumentation to function properly, please see your platform's respective integration guide (iOS, Android) for more information on the steps required to implement rewards in your application.

Server-Side Reward Granting

Campaigns in Upsight that grant users rewards can have the reward be granted either client-side, via the SDK, or server-side. Server-Side reward granting allows Upsight to directly contact your server with the information on which users have been granted which rewards.

To configure Server-Side reward granting, click on the Configure Server-to-Server Callback link from within the Rewards section of the Application's settings.

Within the configuration page, there will be two fields to complete:

  • The Callback URL
  • The Private Key

Callback URL

The Callback URL is the address of your server that Upsight will make an HTTP request to to inform you that a user has received an award. There are various macros available that will be replaced with the values for the specific user and reward being granted. These are:

  • app_token - This is the Application's Public Token. You can use this if you plan to have a single URL to accept callbacks from multiple applications to identify which application the reward is being granted from.
  • sid - This is the user's Unique Upsight ID
  • idfv - This is the user's Unique Vendor ID for Apple and Google
  • reward - This is the ID of the reward granted to the user
  • quantity - This is the quantity of the reward item granted to the user
  • unique_id - This is a unique ID for the specific transaction granting the user the reward, so that you can ensure that each reward is only granted once

To construct your Callback URL, enter your hostname and path, followed by the parameters and macros you wish to receive, for example:

https://www.mysite.com/games/rewards/grant?app={app_token}&user={sid}&reward={reward}&quantity={quantity}&transaction_id={unique_id}

Note that the URL parameters may be named according to what your server expects and do not need to be exactly the same as the macro names.

Private Key

The Private Key is a key of your choice which will be used to sign the request that Upsight makes to your server, so you can verify that the request was made legitimately by Upsight and not by any other party that may have discovered your reward URL.

For more information on the signing and verification process, see our documentation here.

Testing

Once you have entered the Callback URL and Private Key, you can test that the Callback is working. You may enter values for the macros, or have random values generated for the various ID fields.

The Preview button will show an example of the completed URL that will be called, as well as what the Authorization header will look like. You may use these in your verification without Upsight making a call to your server. Once you have completed your implementation, the Test button will make a live call with the entered information. You may wish to use a specific sid or unique_id in your testing so you may prevent rewards from being granted to real users.

The test is considered successful when we receive an HTTP 200 response.

Once the test is successful, you may save the Callback in an enabled state. If you are unable to complete a successful test, but which to save your progress, use the toggle at the top of the page to set the callback to a disabled state before saving.