User Badges API

The User Badges API provides app developers with comprehensive badge data to build custom achievement systems in their React Native applications. Upshot.ai provides a user-specific list of all earned and yet-to-be-earned badges data. Using this data, you can implement a comprehensive Badges section in your application to showcase user achievements and motivate continued engagement.

For Developers

This is a data API for building your own badges interface. You'll receive structured badge information that you can use to create custom badges screens, progress tracking, and achievement celebrations in your React Native app.

Overview

The User Badges API provides developers with:

• Earned Badges Data - Complete collection of badges the user has successfully earned
• Available Badges Data - Badges that are available but not yet earned (with progress tracking)

How User Badges Work

Badge States

1. Available Badge - User can work toward earning this badge

   • Shows progress percentage (0-99%)
   • Displays requirements and description
   • Updates as user makes progress

2. Earned Badge - User has completed requirements and earned the badge

   • Shows earned date and time
   • Progress shows 100%
   • Becomes part of user's permanent collection

Example Flow

User starts app → 0% progress on "First Login" badge
User logs in → Badge earned! → Moves to earned badges collection
User sees "Power User" badge → 20% progress → Continues using app
User completes activities → 40%, 60%, 80% progress
User hits target → Badge earned! → Added to collection

How to Fetch User Badges

Request user badges data:

JavaScript

import Upshot from "react-native-upshotsdk";
// Fetch user badges
Upshot.getUserBadges(function (response) {
  console.log("User badges fetched successfully");
  console.log("Earned badges:", response.active_list);
  console.log("Available badges:", response.inactive_list);

  // Process earned badges
  response.active_list.forEach((badge) => {
    console.log(`✅ ${badge.title}: ${badge.badgeDesc}`);
    console.log(
      `Earned on: ${new Date(badge.achivedTime).toLocaleDateString()}`
    );
  });

  // Process available badges
  response.inactive_list.forEach((badge) => {
    console.log(`🎯 ${badge.title}: ${badge.badgeDesc}`);
  });
});

TypeScript

import Upshot from "react-native-upshotsdk";
interface UserBadgesResponse {
  active_list: Badge[];
  inactive_list: Badge[];
}

interface Badge {
  badge: string;
  activityName: string;
  title: string;
  badgeDesc: string;
  badgeImage: string;
  campaignName: string;
  status: number;
  tags: string[];
  achivedTime?: number; // Only present in active_list
}

// Fetch user badges
Upshot.getUserBadges((response: UserBadgesResponse) => {
  console.log("User badges fetched successfully");
  console.log("Earned badges:", response.active_list);
  console.log("Available badges:", response.inactive_list);
});

Response Structure

The user badges response contains two main arrays:

Active List (Earned Badges)

Badges that the user has already earned:

{
  "active_list": [
    {
      "achivedTime": 1493892162263,
      "activityName": "Badge1",
      "badge": "590c28142b2f15cf1b7b23d3590c39c12b2f15a7517b23c9",
      "badgeDesc": "YOU HAVE WON A FREE PIZZA FROM US :)",
      "badgeImage": "{128, 128}",
      "campaignName": "Campaign1",
      "status": 1,
      "tags": ["Welcome"],
      "title": "CONGRATULATIONS!!!"
    }
  ]
}

Inactive List (Available Badges)

Badges that are available but not yet earned:

{
  "inactive_list": [
    {
      "activityName": "Badge2",
      "badge": "590c397c2b2f15a9517b23c6590c3e5a2b2f152b5a7b23cc",
      "badgeDesc": "You have received two free movie tickets! To accept them, please click the okay button.",
      "badgeImage": "{128, 128}",
      "campaignName": "Campaign2",
      "status": 2,
      "tags": ["Welcome"],
      "title": "Dear Customer!!!"
    }
  ]
}

Response Field Descriptions

Field	Description
active_list	Array of badges the user has earned
inactive_list	Array of badges available but not yet earned
achivedTime	Timestamp when badge was earned (only in active_list)
activityName	Internal name of the badge activity
badge	Unique badge identifier
badgeDesc	Description text for the badge
badgeImage	Badge image dimensions/reference
campaignName	Campaign this badge belongs to
status	Badge status (1 = earned, 2 = available)
tags	Array of tags associated with the badge
title	Display title for the badge

Implementing a Badges Section

Creating a Badge Collection Screen

Here's how to implement a comprehensive badges section in your app:

import React, { useState, useEffect } from "react";
import { View, Text, FlatList, Image } from "react-native";
import Upshot from "react-native-upshotsdk";
const BadgesScreen = () => {
  const [earnedBadges, setEarnedBadges] = useState([]);
  const [availableBadges, setAvailableBadges] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    loadUserBadges();
  }, []);

  const loadUserBadges = () => {
    Upshot.getUserBadges(function (response) {
      setEarnedBadges(response.active_list || []);
      setAvailableBadges(response.inactive_list || []);
      setLoading(false);
    });
  };

  const renderEarnedBadge = ({ item }) => (
    <View style={styles.earnedBadgeCard}>
      <Image source={{ uri: item.badgeImage }} style={styles.badgeImage} />
      <Text style={styles.badgeTitle}>{item.title}</Text>
      <Text style={styles.badgeDescription}>{item.badgeDesc}</Text>
      <Text style={styles.earnedDate}>
        Earned: {new Date(item.achivedTime).toLocaleDateString()}
      </Text>
      <Text style={styles.campaignName}>Campaign: {item.campaignName}</Text>
      <View style={styles.completeBadge}>
        <Text style={styles.completeText}>✅ EARNED</Text>
      </View>
    </View>
  );

  const renderAvailableBadge = ({ item }) => (
    <View style={styles.availableBadgeCard}>
      <Image
        source={{ uri: item.badgeImage }}
        style={[styles.badgeImage, { opacity: 0.5 }]}
      />
      <Text style={styles.badgeTitle}>{item.title}</Text>
      <Text style={styles.badgeDescription}>{item.badgeDesc}</Text>
      <Text style={styles.campaignName}>Campaign: {item.campaignName}</Text>
      <View style={styles.tagsContainer}>
        {item.tags.map((tag, index) => (
          <Text key={index} style={styles.tag}>
            {tag}
          </Text>
        ))}
      </View>
    </View>
  );

  return (
    <View style={styles.container}>
      <Text style={styles.sectionTitle}>
        🏆 Earned Badges ({earnedBadges.length})
      </Text>
      <FlatList
        data={earnedBadges}
        renderItem={renderEarnedBadge}
        keyExtractor={(item) => item.badge}
        horizontal
        showsHorizontalScrollIndicator={false}
      />

      <Text style={styles.sectionTitle}>
        🎯 Available Badges ({availableBadges.length})
      </Text>
      <FlatList
        data={availableBadges}
        renderItem={renderAvailableBadge}
        keyExtractor={(item) => item.badge}
        numColumns={2}
      />
    </View>
  );
};