### Quick Start: Pull and Start RefRef with Docker Compose

Source: https://refref.ai/docs/platform/self-hosting/docker

Commands to pull the latest RefRef image and start the containers with docker-compose. Requires Docker 20.10+ and Docker Compose.

```bash
# Pull the latest RefRef image
docker pull refref/refref:latest
 
# Create a docker-compose.yml file with the necessary configuration
# Start the containers
docker-compose up -d
```

--------------------------------

### Fire events with refcode

Source: https://refref.ai/docs/platform/installation/attribution-script

When a qualifying event occurs (signup, purchase, etc.), include the refcode in your event creation. This example shows a fetch request to the RefRef API.

```javascript
// After user signs up
await fetch('https://api.refref.app/api/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_API_KEY}`
  },
  body: JSON.stringify({
    productId: 'your-product-id',
    externalId: user.id, // Your user's ID
    eventType: 'signup',
    refcode: storedRefcode, // The refcode from attribution
    metadata: {
      email: user.email,
      signupDate: new Date().toISOString()
    }
  })
});
```

--------------------------------

### Customize Widget Styling

Source: https://refref.ai/docs/platform/installation/widget

Customize the widget's appearance using CSS custom properties. The example shows light and dark theme overrides.

```css
refref-widget {
  --refref-primary-color: #3b82f6;
  --refref-border-radius: 8px;
  --refref-font-family: 'Inter', sans-serif;
  --refref-background: #ffffff;
  --refref-text-color: #1f2937;
}
 
/* Dark theme */
refref-widget[theme="dark"] {
  --refref-background: #1f2937;
  --refref-text-color: #f9fafb;
}
```

--------------------------------

### Sample Docker Compose Configuration for RefRef

Source: https://refref.ai/docs/platform/self-hosting/docker

A docker-compose.yml file defining RefRef, PostgreSQL, and Redis services. Sets environment variables for database and Redis connections, and uses named volumes for data persistence.

```yaml
version: '3.8'
 
services:
  refref:
    image: refref/refref:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/refref
      - REDIS_URL=redis://redis:6379
      # Add other environment variables as needed
    depends_on:
      - db
      - redis
 
  db:
    image: postgres:14
    restart: unless-stopped
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_DB=refref
 
  redis:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redis_data:/data
 
volumes:
  postgres_data:
  redis_data:
```

--------------------------------

### Integrate RefRef: Add attribution script and widget

Source: https://refref.ai/docs/platform

Add the attribution script to track referral codes from URLs and cookies, and embed the referral widget so users can share links and track rewards. Replace 'your-product-id' and 'jwt-token-from-your-backend' with your actual values.

```html
<!-- Attribution Script -->
<script src="https://assets.refref.app/attribution.js" defer></script>
 
<!-- Widget -->
<script src="https://assets.refref.ai/widget.js"></script>
<script>
  window.RefRef.init({
    productId: 'your-product-id',
    token: 'jwt-token-from-your-backend'
  });
</script>
```

--------------------------------

### Initialize Without JWT

Source: https://refref.ai/docs/platform/widget

Initialize the widget without JWT authentication using only externalId. Only use if 'Enforce Referral Authentication' is disabled in product settings.

```javascript
window.RefRef.init({
  productId: 'your-product-id',
  externalId: 'user-123' // Your user's unique identifier
});
```

--------------------------------

### Upgrading RefRef Docker Deployment

Source: https://refref.ai/docs/platform/self-hosting/docker

Commands to pull the latest image and restart containers. Always back up data before upgrading.

```bash
# Pull the latest image (or specific version)
docker pull refref/refref:latest
 
# Restart your containers
docker-compose down
docker-compose up -d
```

--------------------------------

### Initialize & Trigger Widget

Source: https://refref.ai/docs/platform/widget

Basic initialization of the RefRef widget with a JWT token fetched from your backend. The widget displays a floating button once initialized.

```html
<!DOCTYPE html>
<html>
<head>
  <script src="https://assets.refref.ai/widget.js"></script>
</head>
<body>
  <!-- Your content -->
 
  <script>
    // Initialize widget with JWT token from your backend
    fetch('/api/refref-token')
      .then(res => res.json())
      .then(data => {
        window.RefRef.init({
          productId: 'your-product-id',
          token: data.token
        });
      });
  </script>
</body>
</html>
```

--------------------------------

### Add the attribution script tag (CDN)

Source: https://refref.ai/docs/platform/installation/attribution-script

Add this script tag to your website's <head> or before the closing </body> tag. The defer attribute ensures the script runs after the page loads without blocking rendering.

```html
<script src="https://assets.refref.app/attribution.js" defer></script>
```

--------------------------------

### Control Widget Layout

Source: https://refref.ai/docs/platform/installation/widget

Set the widget's layout properties such as width, max-width, and margin using CSS.

```css
refref-widget {
  display: block;
  width: 100%;
  max-width: 600px;
  margin: 0 auto;
}
```

--------------------------------

### Generate JWT Token (Node.js)

Source: https://refref.ai/docs/platform/widget

Generate a JWT token for the widget using Node.js. Requires the jsonwebtoken package and your product's client secret. The token includes required claims: sub, productId, iat, exp. Optional claims: email, name. Expiry recommended 1 hour.

```javascript
import jwt from 'jsonwebtoken';
 
function generateWidgetToken(userId: string, productId: string, userEmail?: string, userName?: string) {
  const payload = {
    sub: userId, // User's unique identifier (required)
    productId: productId, // Your RefRef product ID (required)
    email: userEmail, // Optional
    name: userName, // Optional
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour expiry
  };
 
  const token = jwt.sign(
    payload,
    process.env.REFREF_CLIENT_SECRET, // Product secret from RefRef dashboard
    { algorithm: 'HS256' }
  );
 
  return token;
}
 
// Express.js route example
app.get('/api/refref-token', (req, res) => {
  const user = req.user; // From your authentication system
  const token = generateWidgetToken(
    user.id,
    'your-product-id',
    user.email,
    user.name
  );
 
  res.json({ token });
});
```

--------------------------------

### Add the RefRef Attribution Script Tag

Source: https://refref.ai/docs/platform/attribution-script

Add this script tag to your website's <head> section or before the closing </body> tag. The script initializes automatically when the DOM is ready.

```html
<script src="https://assets.refref.ai/attribution.js"></script>
```

--------------------------------

### Add Widget Script (CDN)

Source: https://refref.ai/docs/platform/installation/widget

Include the RefRef widget script in your page using the CDN URL. The 'defer' attribute ensures the script loads after parsing.

```html
<script src="https://assets.refref.app/widget.js" defer></script>
```

--------------------------------

### Listen to Widget Events

Source: https://refref.ai/docs/platform/installation/widget

Listen to widget events such as 'refref:link-copied', 'refref:shared', 'refref:loaded', and 'refref:error' to handle user actions and errors.

```javascript
const widget = document.querySelector('refref-widget');
 
// When user copies referral link
widget.addEventListener('refref:link-copied', (event) => {
  console.log('Link copied:', event.detail.link);
  // Show success toast
});
 
// When user shares on social media
widget.addEventListener('refref:shared', (event) => {
  console.log('Shared on:', event.detail.platform);
  // Track analytics
});
 
// When widget loads successfully
widget.addEventListener('refref:loaded', (event) => {
  console.log('Widget loaded:', event.detail);
});
 
// When widget encounters an error
widget.addEventListener('refref:error', (event) => {
  console.error('Widget error:', event.detail.message);
});
```

--------------------------------

### Add Widget Script

Source: https://refref.ai/docs/platform/widget

Include the RefRef widget script in your page. The script uses Web Components and loads asynchronously with no additional dependencies.

```html
<script src="https://assets.refref.ai/widget.js"></script>
```

--------------------------------

### Programmatic Control

Source: https://refref.ai/docs/platform/widget

Control the widget programmatically using window.RefRef.open(), close(), and toggle() methods.

```javascript
// Open widget programmatically
window.RefRef.open();
 
// Close widget
window.RefRef.close();
 
// Toggle widget
window.RefRef.toggle();
```

--------------------------------

### Verify script is loaded in browser console

Source: https://refref.ai/docs/platform/installation/attribution-script

Open your browser's developer console and check for the RefRef script. This logs whether the script is loaded.

```javascript
// Check if script loaded
console.log(typeof window.RefRef !== 'undefined' ? 'RefRef loaded' : 'RefRef not loaded');
```

--------------------------------

### Generate JWT Token (Node.js)

Source: https://refref.ai/docs/platform/installation/widget

Generate a JWT token on your backend using the jsonwebtoken library. The token includes the user's externalId, productId, and a 1-hour expiry. Never expose your client secret in frontend code.

```javascript
import jwt from 'jsonwebtoken';
 
function generateWidgetToken(userId: string, productId: string) {
  const payload = {
    externalId: userId, // Your user's ID
    productId: productId, // Your RefRef product ID
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour expiry
  };
 
  const token = jwt.sign(
    payload,
    process.env.REFREF_CLIENT_SECRET, // Your product's client secret
    { algorithm: 'HS256' }
  );
 
  return token;
}
 
// API route example
app.get('/api/refref-token', async (req, res) => {
  const userId = req.user.id; // From your auth system
  const token = generateWidgetToken(userId, 'your-product-id');
 
  res.json({ token });
});
```