Rewards System

Upshot's rewards module helps to reward users based on the actions/activities performed by them on a mobile app or a website. This module allows to boost retention and helps increase user's loyalty towards applications.

Overview

Upshot provides several APIs (methods) to:

Fetch Reward Programs - Get list of active reward programs achieved by the user
View Transaction History - Track all reward transactions and activities
Access Reward Rules - Understand how users can earn rewards
Redeem Rewards - Allow users to redeem their earned rewards

The rewards system helps you:

Boost user retention through meaningful incentives
Increase user loyalty and engagement
Track user progress and reward achievements
Create gamified experiences that drive specific behaviors

Reward Status

Get a list of active reward programs using the getRewardsList method:

JavaScriptTypeScript

javascript

import Upshot from "react-native-upshotsdk";
// Fetch active reward programs
Upshot.getRewardsList(
  function (response) {
    // Response is in JSON string, parse it
    const rewardsData = JSON.parse(response);
    console.log("Rewards data:", rewardsData);

    // Process each reward program
    rewardsData.data.forEach((program) => {
      console.log(`Program: ${program.display_name}`);
      console.log(`Balance: ${program.balance} points`);
      console.log(`Earned: ${program.rewards_earned}`);
      console.log(`Redeemed: ${program.rewards_redeemed}`);
    });
  },
  function (error) {
    console.log("Error fetching rewards:", error);
  }
);

typescript

import Upshot from "react-native-upshotsdk";
interface RewardProgram {
  program_description: string;
  display_name: string;
  program_name: string;
  programId: string;
  logo_url: string;
  balance: number;
  rewards_redeemed: number;
  rewards_earned: number;
  rewards_penalty: number;
  rewards_expired: number;
}

interface RewardsResponse {
  status: string;
  statusCode: number;
  status_code: number;
  data: RewardProgram[];
}

// Fetch active reward programs
Upshot.getRewardsList(
  (response: string) => {
    // Response is in JSON string, parse it
    const rewardsData: RewardsResponse = JSON.parse(response);
    console.log("Rewards data:", rewardsData);

    // Process each reward program
    rewardsData.data.forEach((program: RewardProgram) => {
      console.log(`Program: ${program.display_name}`);
      console.log(`Balance: ${program.balance} points`);
      console.log(`Earned: ${program.rewards_earned}`);
      console.log(`Redeemed: ${program.rewards_redeemed}`);
    });
  },
  (error: string) => {
    console.log("Error fetching rewards:", error);
  }
);

Sample Response

json

{
  "status": "success",
  "statusCode": 200,
  "status_code": 200,
  "data": [
    {
      "program_description": "",
      "display_name": "",
      "program_name": "Sample",
      "programId": "5dd268259834967b62dd6ff4",
      "logo_url": "https://s3.amazonaws.com/albdock-bk/shared_folder/media/images/5dd26822442c2.png",
      "balance": 60,
      "rewards_redeemed": 20,
      "rewards_earned": 120,
      "rewards_penalty": 40,
      "rewards_expired": 0
    }
  ]
}

Redeem Rewards

Use the redeemRewardsForProgram method to request reward redemption. Upshot will check the user's balance against the redeem value and provide the status of the request.

JavaScriptTypeScript

javascript

import Upshot from "react-native-upshotsdk";
// Redeem rewards for a program
const programId = "5dd268259834967b62dd6ff4";
const transactionValue = 100.0;
const redeemAmount = 50;
const tag = "discount";

Upshot.redeemRewardsForProgram(
  programId,
  transactionValue,
  redeemAmount,
  tag,
  function (response) {
    // Response is in JSON string, parse it
    const redeemData = JSON.parse(response);
    console.log("Redeem response:", redeemData);

    if (redeemData.status === "success") {
      console.log("Rewards redeemed successfully!");
      // Handle successful redemption
      showSuccessMessage("Rewards redeemed successfully!");
    } else {
      console.log("Redemption failed:", redeemData.statusCode);
      // Handle redemption failure
      showErrorMessage(redeemData.statusCode || "Redemption failed");
    }
  },
  function (error) {
    console.log("Error redeeming rewards:", error);
    showErrorMessage("Unable to redeem rewards. Please try again.");
  }
);

typescript

import Upshot from "react-native-upshotsdk";
interface RedeemResponse {
  status: string;
  statusCode: number;
  statusMessage?: string;
}

// Redeem rewards for a program
const programId: string = "5dd268259834967b62dd6ff4";
const transactionValue: number = 100.0;
const redeemAmount: number = 50;
const tag: string = "discount";

Upshot.redeemRewardsForProgram(
  programId,
  transactionValue,
  redeemAmount,
  tag,
  (response: string) => {
    // Response is in JSON string, parse it
    const redeemData: RedeemResponse = JSON.parse(response);
    console.log("Redeem response:", redeemData);

    if (redeemData.status === "success") {
      console.log("Rewards redeemed successfully!");
      // Handle successful redemption
      showSuccessMessage("Rewards redeemed successfully!");
    } else {
      console.log("Redemption failed:", redeemData.statusMessage);
      // Handle redemption failure
      showErrorMessage(redeemData.statusMessage || "Redemption failed");
    }
  },
  (error: string) => {
    console.log("Error redeeming rewards:", error);
    showErrorMessage("Unable to redeem rewards. Please try again.");
  }
);

Parameters for Reward Redemption

Program ID - ID of the active reward program (can be fetched from status API)
Transaction Value - Value of the transaction
Redeem Value - Value of rewards to be redeemed
Tag - Type/category of rewards to be redeemed

Sample Responses

Success Response:

json

{
  "status": "success",
  "statusCode": 200
}

Failure Response:

json

{
  "status": "Failed",
  "statusCode": 200,
  "statusMessage": "balance insufficient"
}

Reward History

Use the getRewardHistoryForProgram method to get the transaction history for a specific reward program based on programId and historyType.

JavaScriptTypeScript

javascript

import Upshot from "react-native-upshotsdk";
// Transaction types
const HISTORY_TYPES = {
  REWARD_ENTIRE_HISTORY: 0, // includes all transaction types
  REWARD_EARN_HISTORY: 1, // shows only earned history
  REWARD_EXPIRY_HISTORY: 2, // shows expired history
  REWARD_REDEEM_HISTORY: 3, // shows only redeemed history
  REWARD_NEGATIVE_HISTORY: 4, // shows negative history
};

// Fetch reward history
const programId = "5dd268259834967b62dd6ff4";
const transactionType = HISTORY_TYPES.REWARD_ENTIRE_HISTORY;

Upshot.getRewardHistoryForProgram(
  programId,
  transactionType,
  function (response) {
    // Response is in JSON string, parse it
    const historyData = JSON.parse(response);
    console.log("History data:", historyData);

    // Process transaction history
    historyData.data.forEach((transaction) => {
      const date = new Date(transaction.transaction_date * 1000);
      console.log(`Date: ${date.toLocaleDateString()}`);
      console.log(
        `Type: ${getTransactionTypeName(transaction.transaction_type)}`
      );
      console.log(`Value: ${transaction.reward_value}`);
      console.log(`Tag: ${transaction.tag}`);
    });
  },
  function (error) {
    console.log("Error fetching history:", error);
  }
);

// Helper function to get transaction type name
function getTransactionTypeName(type) {
  const types = {
    1: "Earned",
    2: "Expired",
    3: "Redeemed",
    4: "Penalty",
  };
  return types[type] || "Unknown";
}

typescript

import Upshot from "react-native-upshotsdk";
// Transaction types enum
enum HistoryTypes {
  REWARD_ENTIRE_HISTORY = 0, // includes all transaction types
  REWARD_EARN_HISTORY = 1, // shows only earned history
  REWARD_EXPIRY_HISTORY = 2, // shows expired history
  REWARD_REDEEM_HISTORY = 3, // shows only redeemed history
  REWARD_NEGATIVE_HISTORY = 4, // shows negative history
}

interface Transaction {
  transaction_value: number | null;
  transaction_type: number;
  transaction_date: number;
  reward_value: number;
  tag: string;
}

interface HistoryResponse {
  status: string;
  statusCode: number;
  status_code: number;
  data: Transaction[];
}

// Fetch reward history
const programId: string = "5dd268259834967b62dd6ff4";
const transactionType: HistoryTypes = HistoryTypes.REWARD_ENTIRE_HISTORY;

Upshot.getRewardHistoryForProgram(
  programId,
  transactionType,
  (response: string) => {
    // Response is in JSON string, parse it
    const historyData: HistoryResponse = JSON.parse(response);
    console.log("History data:", historyData);

    // Process transaction history
    historyData.data.forEach((transaction: Transaction) => {
      const date = new Date(transaction.transaction_date * 1000);
      console.log(`Date: ${date.toLocaleDateString()}`);
      console.log(
        `Type: ${getTransactionTypeName(transaction.transaction_type)}`
      );
      console.log(`Value: ${transaction.reward_value}`);
      console.log(`Tag: ${transaction.tag}`);
    });
  },
  (error: string) => {
    console.log("Error fetching history:", error);
  }
);

// Helper function to get transaction type name
function getTransactionTypeName(type: number): string {
  const types: { [key: number]: string } = {
    1: "Earned",
    2: "Expired",
    3: "Redeemed",
    4: "Penalty",
  };
  return types[type] || "Unknown";
}

Transaction Types

RewardEntireHistory (0) - Includes all transaction types
RewardEarnHistory (1) - Shows only earned history
RewardExpiryHistory (2) - Shows expired history
RewardRedeemHistory (3) - Shows only redeemed history
RewardNegativeHistory (4) - Shows negative/penalty history

Sample Response

json

{
  "status": "success",
  "statusCode": 200,
  "status_code": 200,
  "data": [
    {
      "transaction_value": null,
      "transaction_type": 4,
      "transaction_date": 1574090603,
      "reward_value": 10,
      "tag": "pumping"
    },
    {
      "transaction_value": null,
      "transaction_type": 1,
      "transaction_date": 1574091350,
      "reward_value": 60,
      "tag": "pumping"
    }
  ]
}

Reward Rules

Use the getRewardRulesforProgram method to get the list of rules with name, description, and tag associated for a given programId.

JavaScriptTypeScript

javascript

import Upshot from "react-native-upshotsdk";
// Fetch earning rules for rewards
const programId = "5dd268259834967b62dd6ff4";

Upshot.getRewardRulesforProgram(
  programId,
  function (response) {
    // Response is in JSON string, parse it
    const rulesData = JSON.parse(response);
    console.log("Rules data:", rulesData);

    // Process reward rules
    console.log(`Program: ${rulesData.data.programId}`);
    console.log(`Description: ${rulesData.data.program_description}`);

    rulesData.data.rules.forEach((rule) => {
      console.log(`Rule: ${rule.rule_name}`);
      console.log(`Description: ${rule.rule_description}`);
      console.log(`Tag: ${rule.tag}`);
      console.log(`Rule ID: ${rule.ruleId}`);
    });
  },
  function (error) {
    console.log("Error fetching rules:", error);
  }
);

typescript

import Upshot from "react-native-upshotsdk";
interface RewardRule {
  rule_name: string;
  ruleId: string;
  tag: string;
  rule_description: string;
}

interface RulesData {
  programId: string;
  program_description: string;
  rules: RewardRule[];
}

interface RulesResponse {
  status: string;
  statusCode: number;
  status_code: number;
  data: RulesData;
}

// Fetch earning rules for rewards
const programId: string = "5dd268259834967b62dd6ff4";

Upshot.getRewardRulesforProgram(
  programId,
  (response: string) => {
    // Response is in JSON string, parse it
    const rulesData: RulesResponse = JSON.parse(response);
    console.log("Rules data:", rulesData);

    // Process reward rules
    console.log(`Program: ${rulesData.data.programId}`);
    console.log(`Description: ${rulesData.data.program_description}`);

    rulesData.data.rules.forEach((rule: RewardRule) => {
      console.log(`Rule: ${rule.rule_name}`);
      console.log(`Description: ${rule.rule_description}`);
      console.log(`Tag: ${rule.tag}`);
      console.log(`Rule ID: ${rule.ruleId}`);
    });
  },
  (error: string) => {
    console.log("Error fetching rules:", error);
  }
);

Parameters

Program ID - ID of the active reward program (can be fetched from status API)

Sample Response

json

{
  "status": "success",
  "statusCode": 200,
  "status_code": 200,
  "data": {
    "programId": "5dd268259834967b62dd6ff4",
    "program_description": "",
    "rules": [
      {
        "rule_name": "World Rule-1",
        "ruleId": "5dd268e6c322233ae963830e",
        "tag": "tag",
        "rule_description": ""
      },
      {
        "rule_name": "World Rule-2",
        "ruleId": "5dd2694a9834967b62dd6ff5",
        "tag": "tag",
        "rule_description": ""
      }
    ]
  }
}

Rewards System ​

Overview ​

Reward Status ​

Sample Response ​

Redeem Rewards ​

Parameters for Reward Redemption ​

Sample Responses ​

Reward History ​

Transaction Types ​

Sample Response ​

Reward Rules ​

Parameters ​

Sample Response ​

Rewards System

Overview

Reward Status

Sample Response

Redeem Rewards

Parameters for Reward Redemption

Sample Responses

Reward History

Transaction Types

Sample Response

Reward Rules

Parameters

Sample Response