Deployment Guide

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

Overview

This guide covers deploying your application (not Resonance infrastructure) to popular platforms. Resonance 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 Resonance SDK integrated
No Resonance infrastructure setup required
No Privy account needed (handled by Resonance)
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
✅ Events configured in Partner Portal → Automation
✅ Production domain added (if using DNS-based detection)

Environment Variables

Required Variables

Only one variable is required:

# Your Resonance Brand ID (get from Partner Portal)
RESONANCE_BRAND_ID=your_brand_id

Or use framework-specific prefixes:

# React (Create React App)
REACT_APP_RESONANCE_BRAND_ID=your_brand_id

# Vite/Next.js
VITE_RESONANCE_BRAND_ID=your_brand_id
NEXT_PUBLIC_RESONANCE_BRAND_ID=your_brand_id

Optional Variables

# Override default API URL (usually not needed)
RESONANCE_API_URL=https://api.rsnc.network

# Override gas relayer URL (usually not needed)
RESONANCE_GAS_RELAYER_URL=https://relayer.rsnc.network

Note: Privy, Supabase, and blockchain configuration are handled by Resonance - 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_RESONANCE_BRAND_ID
# Enter your Brand ID when prompted

# Or via Vercel Dashboard
# Project Settings → Environment Variables
# Add: REACT_APP_RESONANCE_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.rsnc.network/resonance-api/manual-event',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          brandId: process.env.NEXT_PUBLIC_RESONANCE_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_RESONANCE_BRAND_ID = "your_brand_id"

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

2. Set Environment Variables:

# Via Netlify CLI
netlify env:set REACT_APP_RESONANCE_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.RESONANCE_API_URL}/resonance-api/manual-event`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          brandId: process.env.RESONANCE_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.RESONANCE_API_URL}/resonance-api/manual-event`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          brandId: process.env.RESONANCE_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: resonance-integration

provider:
  name: aws
  runtime: nodejs18.x
  region: us-east-1
  environment:
    RESONANCE_BRAND_ID: ${env:RESONANCE_BRAND_ID}
    RESONANCE_API_URL: https://api.rsnc.network

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 RESONANCE_BRAND_ID="your_brand_id"
export RESONANCE_API_URL="https://api.rsnc.network"

# Start with PM2
pm2 start server.js --name resonance-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: resonance-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: RESONANCE_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 RESONANCE_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:
      - RESONANCE_BRAND_ID=your_brand_id
      - NODE_ENV=production
    restart: unless-stopped

Deploy:

# Build image
docker build -t resonance-app .

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

# With docker-compose
docker-compose up -d

Kubernetes Deployment

deployment.yaml:

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

secrets.yaml:

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

Deploy:

# Create secrets
kubectl create secret generic resonance-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('Resonance SDK loaded:', typeof ResonanceAutomation !== 'undefined');
// Should output: true

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

Test Event Tracking:

// In browser console
ResonanceAutomation.track('test_event', {
  userEmail: 'test@example.com',
  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

Resonance 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 support@rsnc.network

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​