Deployment Guide

Complete guide for deploying your application with Loyalteez SDK integration to production.

Overview

This guide covers deploying your application (not Loyalteez infrastructure) to popular platforms. Loyalteez services are already deployed and managed by us - you just need to integrate the SDK into your app.

What You're Deploying:

Your website/application with Loyalteez SDK integrated
No Loyalteez infrastructure setup required
No Privy account needed (handled by Loyalteez)
Just add the SDK script tag and configure your Brand ID

Supported Platforms:

✅ Vercel (Recommended for React/Next.js)
✅ Netlify (Recommended for static sites)
✅ AWS (EC2, Lambda, Amplify)
✅ Digital Ocean
✅ Heroku
✅ Docker/Kubernetes
✅ Any platform that serves HTML/JavaScript

Pre-Deployment Checklist

Before deploying, ensure:

✅ Brand ID obtained from Partner Portal
✅ SDK script tag added to your HTML
✅ Brand ID configured (environment variable or hardcoded)
✅ SDK tested locally
✅ Event tracking tested
✅ Automation enabled in Partner Portal → Settings → LTZ Distribution
✅ Production domain added (if using DNS-based detection)

Environment Variables

Required Variables

Only one variable is required:

# Your Loyalteez Brand ID (get from Partner Portal)
LOYALTEEZ_BRAND_ID=your_brand_id

Or use framework-specific prefixes:

# React (Create React App)
REACT_APP_LOYALTEEZ_BRAND_ID=your_brand_id

# Vite/Next.js
VITE_LOYALTEEZ_BRAND_ID=your_brand_id
NEXT_PUBLIC_LOYALTEEZ_BRAND_ID=your_brand_id

Optional Variables

# Override default API URL (usually not needed)
LOYALTEEZ_API_URL=https://api.loyalteez.app

# Override gas relayer URL (usually not needed)
LOYALTEEZ_GAS_RELAYER_URL=https://relayer.loyalteez.app

Note: Privy, Supabase, and blockchain configuration are handled by Loyalteez - you don't need to configure these.

Vercel Deployment

For React/Next.js Apps

1. Install Vercel CLI:

npm install -g vercel

2. Create vercel.json (optional):

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist"
}

Note: Environment variables are set in Vercel Dashboard, not in vercel.json (for security).

3. Set Environment Variables:

# Via CLI
vercel env add REACT_APP_LOYALTEEZ_BRAND_ID
# Enter your Brand ID when prompted

# Or via Vercel Dashboard
# Project Settings → Environment Variables
# Add: REACT_APP_LOYALTEEZ_BRAND_ID = your_brand_id

4. Deploy:

# Preview deployment
vercel

# Production deployment
vercel --prod

5. Custom Domain:

# Add domain
vercel domains add yourdomain.com

# Configure DNS
# Add CNAME record: www → cname.vercel-dns.com
# Add A record: @ → 76.76.21.21

For Next.js API Routes

Optional: Backend API Route for Manual Event Tracking

If you need to track events from your backend (server-side), create an API route:

pages/api/track-event.js:

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }
  
  const { eventType, userEmail, metadata } = req.body;
  
  try {
    const response = await fetch(
      'https://api.loyalteez.app/loyalteez-api/manual-event',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          brandId: process.env.NEXT_PUBLIC_LOYALTEEZ_BRAND_ID,
          eventType,
          userEmail,
          metadata
        })
      }
    );
    
    const data = await response.json();
    res.status(200).json(data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

Note: Most developers use the SDK directly in the browser - backend API routes are optional.

Netlify Deployment

For Static Sites

1. Create netlify.toml:

[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  REACT_APP_LOYALTEEZ_BRAND_ID = "your_brand_id"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

2. Set Environment Variables:

# Via Netlify CLI
netlify env:set REACT_APP_LOYALTEEZ_BRAND_ID your_brand_id

# Or via Netlify Dashboard
# Site Settings → Build & Deploy → Environment

3. Deploy:

# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod

4. Netlify Functions (Serverless):

netlify/functions/track-event.js:

exports.handler = async (event, context) => {
  if (event.httpMethod !== 'POST') {
    return {
      statusCode: 405,
      body: JSON.stringify({ error: 'Method not allowed' })
    };
  }
  
  const { eventType, userEmail } = JSON.parse(event.body);
  
  try {
    const response = await fetch(
      `${process.env.LOYALTEEZ_API_URL}/loyalteez-api/manual-event`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          brandId: process.env.LOYALTEEZ_BRAND_ID,
          eventType,
          userEmail
        })
      }
    );
    
    const data = await response.json();
    
    return {
      statusCode: 200,
      body: JSON.stringify(data)
    };
  } catch (error) {
    return {
      statusCode: 500,
      body: JSON.stringify({ error: error.message })
    };
  }
};

AWS Deployment

AWS Amplify (Frontend)

1. Install Amplify CLI:

npm install -g @aws-amplify/cli
amplify configure

2. Initialize Amplify:

amplify init

3. Add Environment Variables:

# amplify/backend/amplify-meta.json
{
  "providers": {
    "awscloudformation": {
      "AuthRoleName": "amplify-...",
      "Region": "us-east-1"
    }
  },
  "env": {
    "REACT_APP_BRAND_ID": "your_brand_id",
    "REACT_APP_PRIVY_APP_ID": "your_privy_app_id"
  }
}

4. Deploy:

amplify publish

AWS Lambda (Backend)

handler.js:

exports.trackEvent = async (event) => {
  const body = JSON.parse(event.body);
  const { eventType, userEmail } = body;
  
  try {
    const response = await fetch(
      `${process.env.LOYALTEEZ_API_URL}/loyalteez-api/manual-event`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          brandId: process.env.LOYALTEEZ_BRAND_ID,
          eventType,
          userEmail
        })
      }
    );
    
    const data = await response.json();
    
    return {
      statusCode: 200,
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    };
  } catch (error) {
    return {
      statusCode: 500,
      body: JSON.stringify({ error: error.message })
    };
  }
};

Deploy with Serverless Framework:

# Install Serverless
npm install -g serverless

# serverless.yml
service: loyalteez-integration

provider:
  name: aws
  runtime: nodejs18.x
  region: us-east-1
  environment:
    LOYALTEEZ_BRAND_ID: ${env:LOYALTEEZ_BRAND_ID}
    LOYALTEEZ_API_URL: https://api.loyalteez.app

functions:
  trackEvent:
    handler: handler.trackEvent
    events:
      - http:
          path: track-event
          method: post
          cors: true

# Deploy
serverless deploy

AWS EC2 (Node.js App)

1. Launch EC2 Instance:

Amazon Linux 2 or Ubuntu
t2.micro (Free tier eligible)
Open ports: 80, 443

2. Install Node.js:

# SSH into EC2
ssh -i your-key.pem ec2-user@your-instance-ip

# Install Node.js
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs

# Install PM2
sudo npm install -g pm2

3. Deploy Application:

# Clone your repo
git clone https://github.com/your-username/your-app.git
cd your-app

# Install dependencies
npm install

# Set environment variables
export LOYALTEEZ_BRAND_ID="your_brand_id"
export LOYALTEEZ_API_URL="https://api.loyalteez.app"

# Start with PM2
pm2 start server.js --name loyalteez-app

# Auto-restart on reboot
pm2 startup
pm2 save

4. Configure Nginx:

# Install Nginx
sudo yum install -y nginx

# Configure reverse proxy
sudo nano /etc/nginx/conf.d/app.conf

/etc/nginx/conf.d/app.conf:

server {
    listen 80;
    server_name yourdomain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

# Start Nginx
sudo systemctl start nginx
sudo systemctl enable nginx

5. SSL with Let's Encrypt:

# Install Certbot
sudo yum install -y certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

# Auto-renew
sudo crontab -e
# Add: 0 12 * * * /usr/bin/certbot renew --quiet

Digital Ocean Deployment

App Platform

1. Create app.yaml:

name: loyalteez-app
region: nyc
services:
  - name: web
    github:
      repo: your-username/your-repo
      branch: main
    build_command: npm run build
    run_command: npm start
    environment_slug: node-js
    envs:
      - key: LOYALTEEZ_BRAND_ID
        value: your_brand_id
    http_port: 3000

2. Deploy:

# Install doctl
brew install doctl  # macOS

# Authenticate
doctl auth init

# Create app
doctl apps create --spec app.yaml

# Monitor deployment
doctl apps list

Droplet (VPS)

Same as AWS EC2 - follow Node.js deployment steps above

Heroku Deployment

1. Create Procfile:

web: npm start

2. Create package.json scripts:

{
  "scripts": {
    "start": "node server.js",
    "build": "npm run build:client"
  }
}

3. Deploy:

# Install Heroku CLI
npm install -g heroku

# Login
heroku login

# Create app
heroku create your-app-name

# Set environment variables
heroku config:set LOYALTEEZ_BRAND_ID=your_brand_id

# Deploy
git push heroku main

# Open app
heroku open

Docker Deployment

Dockerfile:

FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy application files
COPY . .

# Build application
RUN npm run build

# Expose port
EXPOSE 3000

# Start application
CMD ["npm", "start"]

docker-compose.yml:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - LOYALTEEZ_BRAND_ID=your_brand_id
      - NODE_ENV=production
    restart: unless-stopped

Deploy:

# Build image
docker build -t loyalteez-app .

# Run container
docker run -d \
  -p 3000:3000 \
  -e LOYALTEEZ_BRAND_ID=your_brand_id \
  --name loyalteez-app \
  loyalteez-app

# With docker-compose
docker-compose up -d

Kubernetes Deployment

deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: loyalteez-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: loyalteez
  template:
    metadata:
      labels:
        app: loyalteez
    spec:
      containers:
      - name: app
        image: your-registry/loyalteez-app:latest
        ports:
        - containerPort: 3000
        env:
        - name: LOYALTEEZ_BRAND_ID
          valueFrom:
            secretKeyRef:
              name: loyalteez-secrets
              key: brand-id
---
apiVersion: v1
kind: Service
metadata:
  name: loyalteez-service
spec:
  selector:
    app: loyalteez
  ports:
  - port: 80
    targetPort: 3000
  type: LoadBalancer

secrets.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: loyalteez-secrets
type: Opaque
data:
  brand-id: base64_encoded_brand_id

Deploy:

# Create secrets
kubectl create secret generic loyalteez-secrets \
  --from-literal=brand-id=your_brand_id

# Apply deployment
kubectl apply -f deployment.yaml

# Check status
kubectl get pods
kubectl get services

Post-Deployment

1. Verify SDK Integration

Check Browser Console:

// Open browser console on your deployed site
console.log('Loyalteez SDK loaded:', typeof LoyalteezAutomation !== 'undefined');
// Should output: true

// Check initialization
LoyalteezAutomation.init('YOUR_BRAND_ID');

Test Event Tracking:

// In browser console
LoyalteezAutomation.track('test_event', {
  userEmail: '[email protected]',
  metadata: { source: 'deployment_test' }
});

// Check Partner Portal → Analytics to verify event was received

Verify in Partner Portal:

Go to Partner Portal → Analytics
Look for your test event
Verify event data is correct

2. Monitor Logs

Vercel:

vercel logs

Netlify:

netlify logs

AWS:

aws logs tail /aws/lambda/your-function --follow

Heroku:

heroku logs --tail

3. Set Up Alerts

Sentry (Error Tracking):

npm install @sentry/node

# Initialize
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.NODE_ENV
});

Datadog (Monitoring):

npm install dd-trace

# Initialize
require('dd-trace').init({
  analytics: true
});

SSL/HTTPS

All platforms automatically provide SSL certificates:

✅ Vercel: Automatic SSL
✅ Netlify: Automatic SSL
✅ AWS Amplify: Automatic SSL
✅ Heroku: Automatic SSL
⚠️ EC2/Droplet: Manual (use Let's Encrypt)

Custom Domains

Vercel

vercel domains add yourdomain.com

DNS Configuration:

Type: CNAME
Name: www
Value: cname.vercel-dns.com

Type: A
Name: @
Value: 76.76.21.21

Netlify

DNS Configuration:

Type: CNAME
Name: www
Value: your-site.netlify.app

Type: A
Name: @
Value: 75.2.60.5

Troubleshooting

Build Failures

Check:

Node version matches local
All dependencies in package.json
Build command is correct
Environment variables are set

Environment Variables Not Working

Check:

Prefix matches framework (REACT_APP_, VITE_, NEXT_PUBLIC_, etc.)
Variables are set in deployment platform dashboard
Rebuild/redeploy after adding variables (most common issue)
Variable names match exactly (case-sensitive)
For client-side: Use public prefix (REACT_APP_, VITE_, NEXT_PUBLIC_)
Check browser console for undefined values

CORS Errors

Solution:

// Add CORS middleware
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  next();
});

Production Checklist

Loyalteez Integration:

✅ Brand ID configured as environment variable
✅ SDK script tag added to HTML
✅ SDK initialization tested
✅ Event tracking tested
✅ Automation enabled in Partner Portal
✅ Production domain added (if using DNS detection)

Your Application:

Need Help? Join our Discord or email [email protected]

Overview​

Pre-Deployment Checklist​

Environment Variables​

Required Variables​

Optional Variables​

Vercel Deployment​

For React/Next.js Apps​

For Next.js API Routes​

Netlify Deployment​

For Static Sites​

AWS Deployment​

AWS Amplify (Frontend)​

AWS Lambda (Backend)​

AWS EC2 (Node.js App)​

Digital Ocean Deployment​

App Platform​

Droplet (VPS)​

Heroku Deployment​

Docker Deployment​

Kubernetes Deployment​

Post-Deployment​

1. Verify SDK Integration​

2. Monitor Logs​

3. Set Up Alerts​

SSL/HTTPS​

Custom Domains​

Vercel​

Netlify​

Troubleshooting​

Build Failures​

Environment Variables Not Working​

CORS Errors​

Production Checklist​

Related Documentation​