BricqsBricqs
Documentation

Events & Callbacks

Complete reference for all events emitted by Bricqs across all integration methods. Use these to sync your application state, trigger analytics, and create custom UI feedback.

Event Delivery Methods

Events are delivered differently depending on your integration method:

IntegrationDelivery MethodSyntax
Script TagGlobal APIbricqs.on('event:name', handler)
iframePostMessagewindow.addEventListener('message', ...)
React SDKCallback props<BricqsEngagement onPointsAwarded={...} />
Headless SDKHook return values + auto-refreshquiz.actionResults.points_awarded

Event Reference

activity:completed

Core

Fired when an individual activity (quiz, spin wheel, form, poll, survey) within an engagement is completed.

// Payload
{
  activityType: 'quiz' | 'spin_wheel' | 'form' | 'poll' | 'survey';
  activityId: string;
  engagementId: string;
  sessionId: string;
  participantId: string;
  completedAt: string; // ISO 8601

  // Activity-specific data
  score?: number;       // Quiz score (0-100)
  maxScore?: number;    // Quiz max possible score
  passed?: boolean;     // Quiz pass/fail
  result?: string;      // Spin wheel — won segment label
  responses?: object;   // Form/survey — submitted data
  selectedOptions?: string[]; // Poll — chosen options
}
Script: bricqs.on('activity:completed', fn)  | PostMessage: bricqs:activity:completed  | React: onActivityComplete

points:awarded

Gamification

Fired when points are awarded to a participant, typically as an on-completion action.

// Payload
{
  points: number;      // Points awarded in this action
  newBalance: number;  // Updated total balance
  reason: string;      // e.g. "quiz_completion", "spin_wheel_win"
  engagementId: string;
  sessionId: string;
}
Script: bricqs.on('points:awarded', fn)  | PostMessage: bricqs:points:awarded  | React: onPointsAwarded
Headless: Triggers auto-refresh on usePoints() and useTier() hooks.

badge:unlocked

Gamification

Fired when a badge is unlocked for a participant.

// Payload
{
  badgeCode: string;   // Unique badge identifier
  badgeName: string;   // Display name
  badgeIcon: string;   // Icon URL
  rarity: 'common' | 'rare' | 'epic' | 'legendary';
  engagementId: string;
  sessionId: string;
}
Script: bricqs.on('badge:unlocked', fn)  | PostMessage: bricqs:badge:unlocked  | React: onBadgeUnlocked
Headless: Triggers instant refresh on useBadges() hook.

reward:claimed

Rewards

Fired when a reward (coupon, voucher, digital, physical) is claimed by a participant.

// Payload
{
  claimId: string;
  rewardName: string;
  rewardType: 'coupon' | 'voucher' | 'physical' | 'digital' | 'points_multiplier';
  codeValue: string | null;  // The actual coupon/voucher code
  value: number | null;       // Monetary value
  expiresAt: string | null;   // ISO 8601
  rewardDefinitionId: string;
  engagementId: string;
  sessionId: string;
}
Script: bricqs.on('reward:claimed', fn)  | PostMessage: bricqs:reward:claimed  | React: onRewardClaimed
Headless: Triggers instant refresh on useRewards() hook.

tier:changed

Progression

Fired when a participant's tier changes (upgrade or downgrade).

// Payload
{
  previousTier: string | null;  // Previous tier name
  newTier: string;              // New tier name
  tierLevel: number;            // Numeric tier level
  tierColor: string;            // Hex color
  engagementId: string;
  sessionId: string;
}
Script: bricqs.on('tier:changed', fn)  | PostMessage: bricqs:tier:changed  | React: onTierChanged
Headless: Triggers auto-refresh on useTier() and usePoints() hooks.

engagement:completed

Core

Fired when all activities in an engagement are completed by the participant.

// Payload
{
  engagementId: string;
  completedAt: string; // ISO 8601
  sessionId: string;
  participantId: string;
  totalActivities: number;
  totalPoints: number; // Cumulative points earned
}
Script: bricqs.on('engagement:completed', fn)  | PostMessage: bricqs:engagement:completed  | React: onComplete

challenge:milestone_reached

Challenge

Fired when a challenge milestone is reached by the participant.

// Payload
{
  challengeId: string;
  milestoneName: string;
  milestoneIndex: number;
  progressPercentage: number;
  engagementId: string;
  sessionId: string;
}
Headless: Reflected in useChallenge().progress after auto-refresh.

Action Results (Headless SDK)

When using headless hooks, server-side action results are returned directly after activity submission. The actionResults object aggregates all on-completion action outcomes.

// After quiz.submit(), form.submit(), etc.
const results = activity.actionResults;

// Structure
{
  points_awarded: number;           // Total points awarded
  new_balance: number;              // Updated points balance
  badges_unlocked: [                // Badges earned
    { code: string, name: string, icon: string }
  ];
  tier_upgrade: {                   // Tier change (if any)
    previous_tier: string | null,
    new_tier: string,
    tier_level: number
  } | null;
  reward_claimed: {                 // Reward claimed (if any)
    claim_id: string,
    reward_name: string,
    reward_type: string,
    code_value: string | null,
    value: number | null,
    expires_at: string | null
  } | null;
  challenge_progress: {             // Challenge update (if any)
    challenge_id: string,
    progress_percentage: number,
    completed_objectives: number,
    milestone_reached: string | null
  } | null;
}

Integration Patterns

Analytics Integration

// Google Analytics 4
bricqs.on('activity:completed', (data) => {
  gtag('event', 'bricqs_activity_completed', {
    activity_type: data.activityType,
    score: data.score,
    engagement_id: data.engagementId,
  });
});

bricqs.on('points:awarded', (data) => {
  gtag('event', 'bricqs_points_awarded', {
    points: data.points,
    new_balance: data.newBalance,
  });
});

bricqs.on('reward:claimed', (data) => {
  gtag('event', 'bricqs_reward_claimed', {
    reward_name: data.rewardName,
    reward_type: data.rewardType,
    value: data.value,
  });
});

Custom Notifications

// Show toast notifications for gamification events
bricqs.on('points:awarded', (data) => {
  toast.success(`+${data.points} points!`, { icon: '⭐' });
});

bricqs.on('badge:unlocked', (data) => {
  toast(`Badge unlocked: ${data.badgeName}`, {
    icon: '🏆',
    duration: 5000,
  });
});

bricqs.on('tier:changed', (data) => {
  confetti();
  toast(`Welcome to ${data.newTier}!`, { icon: '🎉' });
});

bricqs.on('reward:claimed', (data) => {
  showModal({
    title: 'You won a reward!',
    body: `${data.rewardName}: ${data.codeValue}`,
  });
});

State Sync

// Sync Bricqs data with your app state
bricqs.on('points:awarded', (data) => {
  // Update your Redux/Zustand store
  store.dispatch(updatePoints(data.newBalance));
});

bricqs.on('engagement:completed', (data) => {
  // Update user profile
  api.patch('/users/me', {
    completedEngagements: [...user.completedEngagements, data.engagementId],
  });
  // Redirect
  router.push('/thank-you');
});

Next Steps

API Reference →

REST API endpoints, authentication, and rate limits.

Configuration →

API keys, theming, and environment setup.