Custom Events Guide

Create and configure custom events to reward unique customer actions specific to your business.

What Are Custom Events?

Custom events allow you to define and reward customer actions that aren't covered by Loyalteez's predefined event types. Unlike standard events like account_creation or newsletter_subscribe, custom events are:

Brand-specific - Created and configured by you in your Partner Portal
Flexible - Support multiple detection methods (URL patterns, form submissions, CSS selectors, webhooks, Discord bots)
Configurable - Set your own reward amounts, limits, and cooldown periods
Persistent - Saved to your account and available across sessions

Use custom events when:

You have unique conversion actions (e.g., "Download Whitepaper", "Book Demo", "Join Webinar")
You want to create reward "Drops" for Discord
You want to reward actions specific to your industry or business model
Standard events don't match your use case

Creating Custom Events

Step 1: Access Automation Settings

Log into Partner Portal
Navigate to Settings → LTZ Distribution
Click the Automation tab
Click "Create Custom Event" button

Step 2: Define Basic Information

Event Name (Required)

Choose a clear, descriptive name (e.g., "Download Whitepaper", "Discord AMA Reward")
This name appears in your analytics and event list
Minimum 3 characters

Description (Required)

Explain what this event represents and when it should trigger
Helps you remember the purpose later
Minimum 10 characters

Category (Optional)

Select from predefined categories: Account, Commerce, Engagement, Feedback, Custom
Used for organization and filtering

Example:

Name: Discord AMA Reward
Description: Reward for attending the monthly AMA session
Category: Engagement

Step 3: Configure Rewards

Default Reward (LTZ) (Required)

Amount of LTZ credits to distribute when this event occurs
Can be adjusted per event configuration later
Minimum: 1 LTZ

Max Claims Per User (Required)

Maximum number of times a single user can earn this reward
Set to 1 for one-time rewards
Set higher for repeatable actions
Minimum: 1

Cooldown (Hours) (Optional)

Time period before a user can earn this reward again
Set to 0 for no cooldown
Useful for preventing abuse of repeatable events

Requires Email (Checkbox)

Whether this event requires a user email address
Checked: Email must be provided for reward distribution
Unchecked: Event can be tracked without email (limited use cases)

Example Configuration:

Default Reward: 50 LTZ
Max Claims Per User: 1
Cooldown: 0 hours
Requires Email: ✓ (checked)

Step 4: Select Detection Methods

Choose one or more detection methods for how this event should be detected:

🤖 Discord Bot Interaction

Generates a slash command for the Loyalteez Discord Bot.

When to Use:

Creating "Reward Drops" in your Discord server
Daily check-in rewards
Role-specific rewards

Configuration:

No additional config needed. The system generates a /drop command for you.

Example:

/drop event_id:custom_123... label:"Claim Reward"

🌐 URL Pattern Detection

Detects when a user lands on a specific page URL.

When to Use:

Success/confirmation pages (e.g., /thank-you, /download-complete)
Page visits that indicate completion of an action

Configuration Options:

Success Page URLs (optional): Comma-separated list of URLs
- Example: /thank-you, /success, /confirmation
Success Page Elements (optional): CSS selectors for elements that appear on success pages
- Example: .success-message, #confirmation, .thank-you

Example:

// Event triggers when user visits /thank-you or /download-complete
{
  method: 'url_pattern',
  urlPatterns: ['/thank-you', '/download-complete'],
  successSelectors: ['.success-message', '#confirmation']
}

📝 Form Submission Detection

Detects successful submission of a specific form.

When to Use:

Contact forms, newsletter signups, lead generation forms
Any form submission that should trigger a reward

Configuration Options:

Form Selectors (optional): CSS selectors for specific forms
- Example: #contact-form, .newsletter-signup, form[name='booking']
Email Field Name: Name of the email input field (default: email)
Success Indicators (optional): Elements that appear after successful submission
- Example: .form-success, .thank-you-message, #submission-complete

Example:

// Event triggers when form with ID "contact-form" is submitted
{
  method: 'form_submission',
  formSelectors: ['#contact-form'],
  emailField: 'email',
  successIndicators: ['.form-success']
}

🎯 CSS Selector Detection

Detects when a specific element is clicked or becomes visible.

When to Use:

Button clicks (e.g., "Download PDF", "Watch Video")
Element visibility (e.g., "Scroll to bottom", "View pricing")
Custom interactions not covered by forms or URLs

Configuration Options:

Target Elements: CSS selectors for elements that trigger the event
- Example: .download-button, #signup-complete, .purchase-confirmation

Example:

// Event triggers when element with class "download-button" is clicked
{
  method: 'css_selector',
  css_selector: '.download-button'
}

🔗 Webhook Integration

Receive events from your backend system or third-party service.

When to Use:

Backend-triggered events (e.g., payment processing, API integrations)
Third-party service integrations (e.g., CRM, marketing automation)
Server-side event tracking

Configuration:

Endpoint: POST https://api.loyalteez.app/loyalteez-api/manual-event
Send events directly from your backend

Example:

// Event triggered via webhook from your backend
{
  method: 'webhook',
  webhook_endpoint: '/api/loyalteez/webhook/custom'
}

Step 5: Save Custom Event

Click "Create Custom Event" to save. The event will:

Appear in your Events list with a "Custom" badge
Be automatically configured with default settings
Be ready to track immediately (if automation is enabled)

Tracking Custom Events

Once created, custom events can be tracked in multiple ways:

Method 1: Discord Bot

If you selected Discord Bot Interaction, simply copy the generated command from the event details in the Partner Portal and paste it into your Discord server:

/drop event_id:custom_abc123...

Method 2: Automatic Detection (SDK)

If you've configured detection methods (URL patterns, form submissions, CSS selectors), the SDK will automatically detect and track events:

<!-- SDK automatically detects events based on your configuration -->
<script src="https://api.loyalteez.app/sdk.js"></script>
<script>
  LoyalteezAutomation.init('YOUR_BRAND_ID');
  // Custom events are automatically tracked based on detection methods
</script>

How It Works:

SDK loads event configurations from /loyalteez-api/event-config endpoint
Sets up detection listeners based on configured detection methods
Automatically tracks events when detection conditions are met
Sends events to Loyalteez API for processing

Detection Methods Supported:

✅ Discord Bot Interaction - Generates slash commands for Discord
✅ URL Pattern Detection - Automatically detects when users visit configured URLs
✅ CSS Selector Detection - Automatically detects clicks on configured elements
✅ Form Submission Detection - Automatically detects form submissions
✅ Webhook Integration - Server-side events via API

Note: Detection methods are loaded automatically when the SDK initializes. No additional configuration needed!

Method 3: Manual SDK Tracking

Track custom events manually using the SDK:

// Track a custom event manually
LoyalteezAutomation.track('custom_YOUR_BRAND_ID_TIMESTAMP', {
  userEmail: '[email protected]',
  metadata: {
    source: 'manual_tracking',
    additionalData: 'any data you want'
  }
});

Method 4: API Webhook

Send custom events directly from your backend:

curl -X POST https://api.loyalteez.app/loyalteez-api/manual-event \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "YOUR_BRAND_ID",
    "eventType": "custom_YOUR_BRAND_ID_TIMESTAMP",
    "userEmail": "[email protected]",
    "metadata": {
      "source": "backend",
      "action": "whitepaper_download"
    }
  }'

Event Name Mapping

Custom events support event name mapping to map your internal event names to Loyalteez event IDs.

Use Case: If your system uses different event names (e.g., newsletter-signup) but you want to track them as a custom event (e.g., custom_abc123_1234567890).

Configuration:

In Partner Portal → Settings → LTZ Distribution → Automation
Edit your custom event configuration
Set Event Name Mapping field
Example: newsletter-signup → maps to your custom event

SDK Usage:

// Track with mapped name
LoyalteezAutomation.track('newsletter-signup', {
  userEmail: '[email protected]'
});

// SDK automatically maps to your custom event ID

Complete Examples

Example 1: Download Whitepaper Event

Setup:

Create custom event: "Download Whitepaper"
Default reward: 100 LTZ
Max claims: 1
Detection: URL Pattern (/thank-you-download)

Tracking:

// Automatic (via URL pattern)
// User visits /thank-you-download → Event tracked automatically

Example 2: Discord Reward Drop

Setup:

Create custom event: "AMA Reward"
Default reward: 50 LTZ
Max claims: 1
Detection: Discord Bot Interaction

Tracking:

// In Discord:
/drop event_id:custom_abc123... label:"Claim AMA Reward"

Setup:

Create custom event: "Share on Social Media"
Default reward: 50 LTZ
Max claims: 5 (user can share multiple times)
Cooldown: 24 hours
Detection: CSS Selector (.share-button)

Tracking:

// Automatic (via CSS selector)
// User clicks .share-button → Event tracked automatically

Best Practices

1. Naming Conventions

✅ Good Names:

"Download Whitepaper"
"Book Demo Call"
"Discord Daily Check-in"

❌ Bad Names:

"Event 1"
"Custom Event"

2. Reward Amounts

Guidelines:

Low-value actions (100-500 LTZ): Downloads, shares, simple engagements
Mid-value actions (500-2,000 LTZ): Signups, form submissions, demos
High-value actions (2,000+ LTZ): Purchases, subscriptions, referrals

3. Detection Method Selection

Choose detection methods based on:

Discord Bot: Best for community rewards
URL Pattern: Best for page-based conversions
Form Submission: Best for form-based actions
CSS Selector: Best for button clicks or element visibility
Webhook: Best for backend-triggered events

API Reference

Custom Event Structure

interface CustomEvent {
  id: string; // Format: custom_{brandId}_{timestamp}
  name: string;
  description: string;
  category: string;
  requiresEmail: boolean;
  defaultReward: number;
  maxClaimsDefault: number;
  cooldownDefault: number; // hours
  detectionMethods: DetectionMethod[];
  isCustom: true;
  brandId: string;
  createdAt: string;
}

Detection Method Types

type DetectionMethod = 
  | { method: 'url_pattern'; configTemplate: { urlPatterns: string[] } }
  | { method: 'form_submission'; configTemplate: { formSelectors: string[] } }
  | { method: 'css_selector'; configTemplate: { css_selector: string } }
  | { method: 'webhook'; configTemplate: { webhook_endpoint: string } }
  | { method: 'discord_interaction'; configTemplate: {} };

Event Handler API - API reference for event tracking
SDK Integration - JavaScript SDK guide
Discord Integration - Discord Bot setup

What Are Custom Events?​

Creating Custom Events​

Step 1: Access Automation Settings​

Step 2: Define Basic Information​

Step 3: Configure Rewards​

Step 4: Select Detection Methods​

🤖 Discord Bot Interaction​

🌐 URL Pattern Detection​

📝 Form Submission Detection​

🎯 CSS Selector Detection​

🔗 Webhook Integration​

Step 5: Save Custom Event​

Tracking Custom Events​

Method 1: Discord Bot​

Method 2: Automatic Detection (SDK)​

Method 3: Manual SDK Tracking​

Method 4: API Webhook​

Event Name Mapping​

Complete Examples​

Example 1: Download Whitepaper Event​

Example 2: Discord Reward Drop​

Example 3: Social Media Share Event​

Best Practices​

1. Naming Conventions​

2. Reward Amounts​

3. Detection Method Selection​

API Reference​

Custom Event Structure​

Detection Method Types​

Related Documentation​

What Are Custom Events?

Creating Custom Events

Step 1: Access Automation Settings

Step 2: Define Basic Information

Step 3: Configure Rewards

Step 4: Select Detection Methods

🤖 Discord Bot Interaction

🌐 URL Pattern Detection

📝 Form Submission Detection

🎯 CSS Selector Detection

🔗 Webhook Integration

Step 5: Save Custom Event

Tracking Custom Events

Method 1: Discord Bot

Method 2: Automatic Detection (SDK)

Method 3: Manual SDK Tracking

Method 4: API Webhook

Event Name Mapping

Complete Examples

Example 1: Download Whitepaper Event

Example 2: Discord Reward Drop

Example 3: Social Media Share Event

Best Practices

1. Naming Conventions

2. Reward Amounts

3. Detection Method Selection

API Reference

Custom Event Structure

Detection Method Types

Related Documentation