Skip to main content

Frequently Asked Questions (FAQ)

Common questions and quick answers for developers integrating with Loyalteez.

🚀 Getting Started​

How do I get started with Loyalteez?​

Quick Answer: Follow our 5-minute Quick Start guide.

Steps:

  1. Get your Brand ID from Partner Portal
  2. Add the SDK script tag to your site
  3. Initialize with your Brand ID
  4. Start tracking events

See Also: Quick Start Guide | SDK Integration

Where do I get my Brand ID?​

Quick Answer: Log into Partner Portal → Settings → Account → Copy your Brand ID.

Format: Looks like brand_abc123...

See Also: Quick Start | User Guide

What's the correct SDK URL?​

Quick Answer: https://api.loyalteez.app/sdk.js

Common Mistake: ❌ cdn.loyalteez.app (doesn't exist)
Correct: ✅ api.loyalteez.app/sdk.js

Example:

<script src="https://api.loyalteez.app/sdk.js"></script>
<script>
  LoyalteezAutomation.init('YOUR_BRAND_ID');
</script>

See Also: SDK Integration | Quick Start

Is there an npm package?​

Quick Answer: No. Loyalteez SDK is delivered as a Cloudflare Worker script, not an npm package.

Why: We use a hosted Worker for automatic updates and better performance.

How to Use:

<!-- ✅ Correct - Script tag -->
<script src="https://api.loyalteez.app/sdk.js"></script>

<!-- ❌ Wrong - npm package doesn't exist -->
npm install @loyalteez/sdk

See Also: SDK Integration | Architecture

🔧 SDK & Integration​

How do I track events?​

Quick Answer: Use LoyalteezAutomation.track() after initializing the SDK.

Example:

// Initialize first
LoyalteezAutomation.init('YOUR_BRAND_ID');

// Track an event
LoyalteezAutomation.track('account_creation', {
  userEmail: '[email protected]',
  metadata: { userId: '123' }
});

Supported Events:

  • account_creation → 100 LTZ
  • newsletter_subscribe → 25 LTZ
  • subscribe_renewal → 200 LTZ
  • complete_survey → 75 LTZ
  • rate_experience → 50 LTZ
  • form_submit → 10 LTZ

See Also: SDK Reference | Event Handler API

Can I use the SDK with React/Next.js/Vue?​

Quick Answer: Yes! The SDK works with any framework.

React Example:

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    if (window.LoyalteezAutomation) {
      window.LoyalteezAutomation.init(process.env.REACT_APP_BRAND_ID);
    }
  }, []);
  
  return <YourApp />;
}

Next.js Example:

import Script from 'next/script';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Script 
        src="https://api.loyalteez.app/sdk.js"
        onLoad={() => {
          LoyalteezAutomation.init(process.env.NEXT_PUBLIC_BRAND_ID);
        }}
      />
      <Component {...pageProps} />
    </>
  );
}

See Also: Quick Start - Framework Examples | React Integration Example

How do I test my integration?​

Quick Answer: Enable debug mode and check the browser console.

Step 1: Enable debug mode:

LoyalteezAutomation.init('YOUR_BRAND_ID', { debug: true });

Step 2: Track a test event:

LoyalteezAutomation.track('test_event', {
  userEmail: '[email protected]',
  metadata: { source: 'console_test' }
});

Step 3: Check console for [Loyalteez] logs and verify in Partner Portal → Analytics.

See Also: Testing Guide | Quick Start - Testing

Why aren't my events being tracked?​

Quick Answer: Check these common issues:

  1. SDK not loaded?

    console.log('SDK loaded:', typeof LoyalteezAutomation !== 'undefined');

  2. Brand ID correct? Verify in Partner Portal → Settings → Account

  3. Automation enabled? Check Partner Portal → Settings → LTZ Distribution → Enable Automation

  4. Debug mode: Enable { debug: true } to see console logs

  5. CORS errors? Ensure you're using HTTPS in production

See Also: Troubleshooting | Error Codes

🌐 API & Endpoints​

What are the API endpoints?​

Quick Answer: Here are the main endpoints:

ServiceURLPurpose
SDKhttps://api.loyalteez.app/sdk.jsJavaScript SDK
Event Confighttps://api.loyalteez.app/loyalteez-api/event-config?brandId=...Get event configurations (used by SDK)
Event Handlerhttps://api.loyalteez.app/loyalteez-api/manual-eventTrack events
Gas Relayerhttps://relayer.loyalteez.app/relayGasless transactions
Pregenerationhttps://api.loyalteez.app/loyalteez-api/pregenerationOAuth wallet creation

Note: The /event-config endpoint is automatically called by the SDK to load your custom event configurations and detection methods. You typically don't need to call it directly.

See Also: REST API Reference | Event Handler API | Gas Relayer API

What's the correct gas relayer URL?​

Quick Answer: https://relayer.loyalteez.app/relay

Common Mistake: ❌ gas-relayer.loyalteez.app (doesn't exist)
Correct: ✅ relayer.loyalteez.app/relay

See Also: Gas Relayer API

How do I handle API errors?​

Quick Answer: Check the error status code and message, then implement appropriate handling.

Common Errors:

  • 400 - Invalid data → Check required fields
  • 403 - Automation disabled → Enable in Partner Portal
  • 429 - Rate limit → Implement deduplication
  • 500 - Server error → Retry with backoff

Example:

try {
  const response = await fetch('https://api.loyalteez.app/loyalteez-api/manual-event', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(eventData)
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error);
    // Handle specific errors
  }
} catch (error) {
  console.error('Network error:', error);
}

See Also: Error Codes Guide | Error Handling Best Practices

🔗 Smart Contracts & Network​

What are the contract addresses?​

Quick Answer: Here are the addresses on Soneium Mainnet:

ContractAddress
Loyalteez Token (LTZ)0x5242b6DB88A72752ac5a54cFe6A7DB8244d743c9
PerkNFT0x6ae30d6Dcf3e75456B6582b057f1Bf98A90F2CA0
PointsSale0x5269B83F6A4E31bEdFDf5329DC052FBb661e3c72

See Also: Quick Start - Contract Addresses

What network does Loyalteez use?​

Quick Answer: Soneium Mainnet (Chain ID: 1868)

Network Configuration:

const SONEIUM_MAINNET = {
  chainId: 1868,
  name: 'Soneium Mainnet',
  rpcUrl: 'https://rpc.soneium.org',
  blockExplorer: 'https://soneium.blockscout.com',
  nativeCurrency: {
    name: 'ETH',
    symbol: 'ETH',
    decimals: 18
  }
};

See Also: Quick Start - Network Config

Do I need to interact with contracts directly?​

Quick Answer: Usually no. The SDK and APIs handle all contract interactions automatically.

When you might need direct access:

  • Custom integrations
  • Advanced gasless transactions
  • Perk claiming flows

See Also: Gas Relayer API | Architecture

🔐 Authentication & Security​

How does authentication work?​

Quick Answer: Loyalteez uses Privy for secure wallet management. Customers don't need to authenticate - wallets are created automatically.

For Gas Relayer: You need a Privy access token:

import { usePrivy } from '@privy-io/react-auth';

const { getAccessToken } = usePrivy();
const token = await getAccessToken();

fetch('https://relayer.loyalteez.app/relay', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

See Also: Authentication Guide | Gas Relayer API

Is my data secure?​

Quick Answer: Yes. Loyalteez uses enterprise-grade security:

  • 256-bit encryption for all data
  • SOC 2 certified infrastructure
  • GDPR compliant privacy controls
  • Row-level security via Supabase
  • Secure wallets powered by Privy

See Also: Architecture - Security

💰 Pricing & Limits​

How much does it cost?​

Quick Answer: Simple pricing: 1 USD = 1,000 LTZ credits

  • No monthly fees
  • No setup costs
  • No transaction fees
  • Pay only for LTZ you distribute

See Also: User Guide - Pricing

What are the rate limits?​

Quick Answer: Rate limits prevent abuse:

ServiceLimit
Event Handler1 reward per event type per user per day
Gas Relayer35 transactions per user per hour
Pregeneration100 requests per brand per minute

See Also: Rate Limits Guide | Error Codes - Rate Limits

🐛 Troubleshooting​

SDK not loading?​

Quick Answer: Check these:

  1. Script tag correct?

    <script src="https://api.loyalteez.app/sdk.js"></script>

  2. Ad blockers? Some ad blockers block the SDK

  3. HTTPS? Use HTTPS in production

  4. Console errors? Check browser console for errors

Debug:

console.log('SDK loaded:', typeof LoyalteezAutomation !== 'undefined');

See Also: Quick Start - Troubleshooting

Getting CORS errors?​

Quick Answer: Loyalteez APIs support CORS by default. If you see CORS errors:

  1. Use HTTPS (not HTTP)
  2. Check headers: 
    headers: {
      'Content-Type': 'application/json' // Required
    }
  3. Verify endpoint URL is correct
  4. Add domain in Partner Portal → Settings → Domains (if needed)

See Also: Error Codes - CORS

Events not appearing in analytics?​

Quick Answer: Check these:

  1. Automation enabled? Partner Portal → Settings → LTZ Distribution
  2. Event type configured? Check reward rules
  3. Rate limited? User may have already received reward today
  4. Debug mode: Enable to see console logs

See Also: Error Codes | Testing Guide

Getting 403 "Automation disabled" error?​

Quick Answer: Enable automation in Partner Portal:

  1. Log into Partner Portal
  2. Go to Settings → LTZ Distribution
  3. Toggle "Enable Automation" to ON
  4. Save settings

See Also: Error Codes - Automation Disabled

📱 Mobile Integration​

Can I use Loyalteez in mobile apps?​

Quick Answer: Yes! Loyalteez supports React Native, iOS, and Android.

React Native:

import { LoyalteezSDK } from '@loyalteez/react-native';

LoyalteezSDK.init('YOUR_BRAND_ID');
LoyalteezSDK.track('account_creation', { userEmail });

See Also: Mobile Integration Overview | React Native Guide | iOS Guide | Android Guide

🔌 Integrations​

Can I create custom events for my specific use case?​

Quick Answer: Yes! You can create custom events in Partner Portal → Settings → LTZ Distribution → Automation.

Custom events allow you to:

  • Define unique actions specific to your business
  • Configure multiple detection methods (URL patterns, form submissions, CSS selectors, webhooks)
  • Set custom reward amounts, limits, and cooldown periods
  • Track events automatically via SDK or manually via API

Detection Methods (Automatic):

  • URL Pattern - Automatically detects when users visit specific pages (e.g., /thank-you, /success)
  • CSS Selector - Automatically detects clicks on specific elements (e.g., .download-button)
  • Form Submission - Automatically detects form submissions (e.g., #contact-form)
  • Webhook - Server-side events via API

How Automatic Detection Works:

  1. Create custom event with detection methods in Partner Portal
  2. SDK automatically loads configurations on initialization
  3. SDK sets up detection listeners based on your configuration
  4. Events are tracked automatically - no code changes needed!

Example Use Cases:

  • Download Whitepaper (URL Pattern: /thank-you-download)
  • Book Demo Call (Form Submission: #demo-form)
  • Complete Survey (CSS Selector: .survey-complete-button)
  • Share on Social Media (CSS Selector: .share-button)
  • Backend-triggered events (Webhook: API call)

See Also: Custom Events Guide | Event Handler API

Can I integrate with Discord/Telegram/Shopify?​

Quick Answer: Yes! Loyalteez supports multiple platforms:

  • Discord - Reward Discord users
  • Telegram - Reward Telegram users
  • Farcaster - Reward Farcaster users
  • Shopify - E-commerce integration
  • Custom - Build your own integration

See Also: Integrations Overview | Discord Integration | Shopify Integration

How do I pregenerate wallets for OAuth users?​

Quick Answer: Use the Pregeneration API before users authenticate:

await fetch('https://api.loyalteez.app/loyalteez-api/pregeneration', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    brandId: 'YOUR_BRAND_ID',
    provider: 'discord',
    userId: '123456789012345678',
    username: 'username'
  })
});

See Also: OAuth Pregeneration Guide | Pregeneration API

🚀 Deployment​

How do I deploy my integration?​

Quick Answer: Deploy your application normally - Loyalteez SDK is just a script tag!

Steps:

  1. Add SDK script tag to your HTML
  2. Set Brand ID as environment variable (or hardcode)
  3. Deploy your app to any platform (Vercel, Netlify, AWS, etc.)
  4. Test SDK loading in production
  5. Monitor analytics in Partner Portal

Important: You're deploying YOUR app, not Loyalteez infrastructure. Loyalteez services are already deployed and managed by us.

See Also: Deployment Guide | Quick Start

📚 More Help​

Where can I find more documentation?​

Quick Answer: Check these resources:

How do I contact support?​

Quick Answer:

When contacting support, include:

  • Your Brand ID
  • Error message (if any)
  • Steps to reproduce
  • Browser/device info

🎯 Quick Links​

Still have questions? Email us at [email protected]

Last updated on