Events Quests

Event Types Overview

Currently, there are two types of events, each with different quest handling approaches:

Normal Events

• Users compete by completing one or more quests at a time

• Quest submissions follow the same approach as standard quests

Score-Based Events

• Quests are automatically tracked, with results defined progressively

• Submissions require synchronization to fetch and process user data (e.g., scores or stats)

To explore the type definitions in detail:

import { NormalEvent, ScoreEvent } from '@xborglabs/ui-shared';

Quest Submission Methods

Normal Events

Use the useMutateQuestSubmit hook, which follows the same workflow as standard quests.

Score-Based Events

Use the useSyncEvent hook to handle synchronization of event data.

Using useSyncEvent Hook

The useSyncEvent hook is specifically designed for score-based events:

function useSyncEvent(eventId: string);

Implementation Example

Here's a complete example of implementing synchronization logic:

import { useSyncEvent } from '@xborglabs/ui-shared/dist/client';

const QUEST_EVENT_SYNC_TIMER = 'qert';

export default function App() {
  const runSync = useSyncEvent(eventId);
  const [syncing, setSyncing] = useState(false);
  const syncStatus = event?.participation?.syncStatus;
  const isSyncing = syncing || syncStatus === ParticipantSyncStatusTypeSchema.Enum.SYNCING;

  useEffect(() => {
    const key = `${QUEST_EVENT_SYNC_TIMER}:${eventId}`;
    const lastRan = localStorage.getItem(key);

    if (lastRan) {
      const lastRanDate = new Date(lastRan);
      const now = new Date();
      if (now.getTime() - lastRanDate.getTime() < 5 * 60 * 1000) {
        return; // Exit if the last run was less than 5 minutes ago
      }
    }
    
    onSync();
  }, [eventId]);

  function onSync() {
    if (isSyncing) {
      return;
    }

    setSyncing(true);
    
    runSync
      .mutateAsync()
      .then(async () => {
        // Refetch events or update UI as necessary
      })
      .catch((err) => {
        console.error('Sync failed:', err);
      })
      .finally(() => {
        setSyncing(false);
      });
  }

  return (
    <button onClick={onSync} disabled={isSyncing}>
      {isSyncing ? 'Syncing...' : 'Sync'}
    </button>
  );
}

Key Features of useSyncEvent

1. Purpose

   • Syncs event data for score-based events

   • Ensures participant stats or scores are updated

2. Input Requirements

   • Requires the eventId to identify the event

3. Debounce Logic

   • Includes a 5-minute cooldown

   • Prevents unnecessary repeated sync attempts

4. UI State Management

   • Uses isSyncing state to indicate ongoing synchronization

   • Provides feedback about sync status to users

Best Practices

1. Normal Events

   • Handle quest submissions like standard quests

   • Use appropriate error handling and loading states

2. Score-Based Events

   • Implement debounce logic to prevent excessive syncs

   • Show clear sync status to users

   • Handle errors gracefully

   • Update UI appropriately after successful syncs

3. General Guidelines

   • Always verify event type before handling quests

   • Implement appropriate loading and error states

   • Consider user feedback for different quest states