Events Requirements

Admins have the possibility to gate events based on requirements, such as owning a specific wearable, have a minimum in-app level,

Schema Definition

The EventRequirementType defines the structure for event requirements:

export type EventRequirementType = {
  name: 'quest_completed'; // Requirement type (currently supports quest completion)
  requirementId: string;   // ID of the requirement
  eventId: string;         // Associated event ID
  requirementArgs: {
    outcome: number;       // Expected outcome (e.g., minimum score or completion percentage)
    questId: string;       // ID of the required quest
  };
  data: {                  // Metadata about the requirement
    id: string;
    title: string;
    createdAt: FlexDate;
    updatedAt: FlexDate;
    locale: string;
    description: ParsableContent[];
  };
};

⚠️ Note: The requirementArgs and data fields are requirement-type specific. For example, a wearable requirement would have a different schema for these fields.

Requirement Validation

Backend Validation

The backend always validates requirements and throws an error if any unmet requirement is detected, ensuring robust eligibility checks.

Client-Side Validation

Although the backend enforces requirement checks, you can implement optional client-side validation for immediate user feedback:

function canJoinEvent(event) {
  if (!event.requirements) return true; // No requirements, user can join

  const unmetRequirements = event.requirements.filter((requirement) => {
    const { questId, outcome } = requirement.requirementArgs;
    const questStatus = ...; // Fetch user's quest status
    return questStatus.outcome < outcome; // Compare user's outcome with required value
  });

  return unmetRequirements.length === 0;
}

if (!canJoinEvent(questEvent)) {
  console.log("You do not meet the requirements to join this event.");
}

Score-Based Events Social Requirements

Score-based events require participants to bind their gaming accounts (e.g., Riot, Steam, Faceit) before joining. This is used to refresh the stats of all the quests nested under a score-based event at once. Also, because joining a score-based event triggers a

Handling Social Binding

The backend validates required social account links when joining score-based events:

import { useMutateParticipateEvent } from '@xborglabs/ui-shared/dist/client';
import { getRequiredSocial } from "@xborglabs/ui-shared";

const mutateJoinEvent = useMutateParticipateEvent();

function joinEvent() {
  mutateJoinEvent.mutate(questEvent.eventId, {
    onError: (err: unknown) => {
      if (err instanceof AxiosError && err.response) {
        const { name, code, details } = err.response.data;

        if (name === "social_not_linked" && code === 10052) {
          const requiredSocial = getRequiredSocial(first(details.types)); // Detect required social account
          setRequiredSocial(requiredSocial); // Update state to prompt social binding
        }
      }
    },
  });
}

Social Binding Redirect

Generate dynamic redirect links for social account binding:

const socialBindingLink = useMemo(() => {
  const redirectTo = `?redirectTo=${encodeURIComponent(
    window.location.pathname + window.location.search,
  )}`;

  switch (requiredSocial) {
    case "STEAM":
      return API_ROUTES.GAMING_CONNECT.STEAM + redirectTo;
    case "RIOT":
      return API_ROUTES.GAMING_CONNECT.RIOT + redirectTo;
    case "FACEIT":
      return API_ROUTES.GAMING_CONNECT.FACEIT + redirectTo;
    case "BATTLENET":
      return API_ROUTES.GAMING_CONNECT.BATTLENET + redirectTo;
    default:
      return "";
  }
}, [requiredSocial]);

if (requiredSocial) {
  window.location.href = socialBindingLink;
}

Implementation Examples

1. Joining an Event

import { CLIENT_QUERY_KEYS } from "@xborglabs/ui-shared";

function joinEvent() {
  if (!authState || !joinState?.isRegistrationOpen) {
    console.log("Registration is closed or user is not authenticated.");
    return;
  }

  mutateJoinEvent.mutate(questEvent.eventId, {
    onSuccess: () => {
      console.log(`Successfully joined the event: ${questEvent.title}`);
      queryClient.invalidateQueries({
        queryKey: [CLIENT_QUERY_KEYS.EVENT_DETAILS],
      });
      queryClient.invalidateQueries({
        queryKey: [CLIENT_QUERY_KEYS.COMMUNITY_EVENTS],
      });
    },
    onError: (err) => {
      console.error("Failed to join the event:", err);
    },
  });
}

2. Displaying Requirements

function displayEventRequirements(event) {
  if (!event.requirements || event.requirements.length === 0) {
    return "No special requirements for this event.";
  }

  return event.requirements.map((req) => {
    return `Requirement: Complete quest "${req.data.title}" with outcome >= ${req.requirementArgs.outcome}.`;
  }).join("\n");
}

console.log(displayEventRequirements(questEvent));

3. Social Binding Redirect

function redirectToSocialBinding() {
  if (!requiredSocial) return;
  window.location.href = socialBindingLink;
}

if (requiredSocial) {
  console.log(`Redirecting user to bind their ${requiredSocial} account...`);
  redirectToSocialBinding();
}

UI Implementation Guidelines

When implementing the UI for event requirements:

1. Display requirements prominently before the join button

2. Show clear validation states for each requirement

3. Provide helpful error messages when requirements aren't met

4. Include direct links to complete required quests

5. Guide users through the social binding process for score-based events