Key Concepts

This guide explains the core concepts and relationships in the Questful platform, helping you understand how different components work together.

Entities and Relationships

    User[User] --> Quest[Quest]
    User --> Reward[Reward]
    Quest --> Reward
    User --> Redemption[Reward Redemption]
    Reward --> Redemption
    User --> Completion[Quest Completion]
    Quest --> Completion
    Completion --> Reward

Core Entities

1. Users

   • Represent your application's users
   • Identified by a unique customerId
   • Can have multiple rewards
   • Can complete multiple quests

2. Quests

   • Tasks or challenges users can complete
   • Associated with specific rewards
   • Can be of different types (standard, daily, social)
   • May require social media verification

3. Rewards

   • Points or items users can earn
   • Can be redeemed for various purposes
   • Tracked with balances per user

4. Quest Completions

   • Records when a user completes a quest
   • Links users to completed quests
   • Triggers reward distribution
   • Maintains completion history
   • Tracks completion timestamps

5. Reward Redemptions

   • Records of users redeeming their rewards
   • Maintains transaction history
   • Updates user reward balances

Users and CustomerId

The customerId is the primary identifier for users in the Questful platform:

• Must be unique within your account
• Can be any string that uniquely identifies a user in your system
• Used across all API endpoints to reference users
• Automatically creates a new user if it doesn't exist

Example:

{
  "customerId": "user_123",
}

Quests and Quest Types

Quest Types

1. Standard Quests

• One-time completion quests
• Can only be completed once per user
• Perfect for tutorial or achievement quests

2. Daily Quests

• Reset every 24 hours
• Can be completed once per day
• Ideal for daily engagement activities

3. Social Quests

• Require social media interaction verification
• Currently supports Twitter follow quests
• Real-time verification of social actions
• Can only be completed once per user
• Perfect for community building and social engagement

Quest Structure

{
  "id": "quest_123",
  "name": "Welcome Quest",
  "description": "Complete your first quest",
  "type": "standard | daily | twitter-follow",
  "rewardAmount": 100,
  "rewardId": "reward_123",
  "status": "live",
  "startDate": "2024-12-31T23:59:59Z",
  "endDate": "2025-12-31T23:59:59Z",
  "socialQuestParams": {
    "twitterFollowParams": {
      "accountToFollowUsername": "questful" // Required for twitter-follow quests
    }
    "twitterRetweetParams": {
            postIdToRetweet: "123"; // Required for twitter-retweet quests
        }
        "twitterCommentParams": {
            postIdToComment: "123"; // Required for twitter-comment quests
        }
  },
  "createdAt": "2024-12-31T23:59:59Z",
  "updatedAt": "2024-12-31T23:59:59Z"
}

Rewards

Rewards are the points or items users can earn and redeem:

Reward Structure

{
  "id": "reward_123",
  "name": "Experience Points",
}

Quest Lifecycle

1. Creation

• Quest is created with specific requirements and rewards
• Can be set as "draft", "published" or "archived"
• Expiration date is required
• For social quests, required social parameters must be configured

2. Publishing

• Quest status is set to "published"
• Quest becomes available to users

3. Completion

• User completes the quest requirements
• For social quests, system verifies the social action (e.g., Twitter follow)
• You make an API call to our system to trigger the quest completion for the user
• Rewards amount is awarded to the user
• Quest is marked as completed

4. Reset/Expiration

• Daily quests reset at midnight UTC
• Social and Standard quests can only be completed once
• Expired quests become unavailable

Reward Lifecycle

1. Earning

• User completes a quest
• System awards specified reward amount
• Balance is updated immediately

2. Accumulation

• Rewards are stored in user's balance
• Can be viewed through API
• Separate balances per reward

3. Redemption

• User requests reward redemption
• System verifies sufficient balance
• Balance is updated after redemption

4. History

• All transactions are recorded
• Includes earning and redemption history
• Can be queried through API

Rewards Redemption Process

1. Initiation

• User requests reward redemption
• You make an API call to our system to process the Redemption
• System checks current balance
• Validates redemption amount

2. Processing

• Deducts amount from balance
• Creates redemption record
• Generates transaction ID

3. Completion

• Updates user's reward balance
• Returns new balance to user
• Records transaction in history

Important Notes

• Redemptions cannot exceed available balance
• Redemption history is permanent and cannot be reversed
• Balances are updated atomically to prevent race conditions
• Social quest verifications are performed in real-time
• Twitter usernames for social quests must be provided without the @ symbol