Advanced Settings and API

Configure advanced features, API access, and developer tools for extended functionality.

Accessing Advanced Settings

Navigate to advanced settings:

Shopify admin → Apps → Alva Digital Downloads
Click Settings → Advanced
Configure developer features

Advanced sections:

• API Access
• Webhooks
• Custom Code
• Developer Tools
• Performance Tuning
• Experimental Features

API Configuration

API Access

Enable API access:

API credentials:

Settings → Advanced → API Access

API Key: [Generate New Key]
Generated: ak_live_abc123def456...
Created: January 15, 2024
Last used: Never

Status: ✓ Active
Rate limit: 1000 requests/hour

Security:

⚠️ Keep API key secret
⚠️ Never commit to version control
⚠️ Regenerate if compromised
⚠️ Use environment variables

Actions:

[Copy API Key]
[Regenerate Key]
[Revoke Access]
[View Usage]

API Authentication

Authentication methods:

Bearer token:

Header: Authorization: Bearer {api_key}
Format: ak_live_abc123def456...
Required: All API requests

Example:
curl -H "Authorization: Bearer ak_live_abc123..." \
  https://yourshop.com/api/files

HMAC signature (webhooks):

Header: X-Alva-HMAC-SHA256
Algorithm: HMAC-SHA256
Secret: Webhook secret
Purpose: Verify webhook authenticity

API Rate Limiting

Rate limit configuration:

Default limits:

Settings → Advanced → API → Rate Limits

Requests per hour: 1000 (default)
Burst limit: 100 per minute
Concurrent requests: 10

Headers returned:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1610000000

Custom limits:

☐ Enable custom rate limits
Hourly: 5000 requests
Burst: 250 per minute

Applies to: This shop only
Enterprise plans: Unlimited

API Endpoints

Available endpoints:

Files API:

GET    /api/files - List all files
GET    /api/files/{id} - Get file details
POST   /api/files/upload - Upload new file
PUT    /api/files/{id} - Update file
DELETE /api/files/{id} - Delete file

Orders API:

GET    /api/orders - List digital orders
GET    /api/orders/{id} - Get order details
POST   /api/orders/{id}/approve - Approve flagged order
POST   /api/orders/{id}/reject - Reject flagged order
GET    /api/orders/{id}/downloads - Get download logs

Downloads API:

POST   /api/downloads/generate - Generate download link
GET    /api/downloads/{token} - Validate download token
POST   /api/downloads/{token}/increment - Track download
DELETE /api/downloads/{token} - Revoke download access

Full documentation:

[View API Documentation]
Interactive: Swagger/OpenAPI
Examples: All languages
Testing: Built-in API explorer

Webhook Configuration

Webhook Setup

Configure webhooks:

Add webhook:

Settings → Advanced → Webhooks → Add Webhook

Endpoint URL: https://yourapp.com/webhooks/alva
Event types: [Select events]
Authentication: HMAC signature
Format: JSON
Timeout: 10 seconds
Retry: 3 attempts with exponential backoff

Webhook Events

Available events:

Order events:

☑ order.created - New digital order
☑ order.approved - Fraud check passed
☑ order.rejected - Fraud check failed
☑ order.fulfilled - Files delivered
☐ order.refunded - Order refunded

Download events:

☑ download.created - New download link
☑ download.accessed - Customer downloaded
☑ download.limit_reached - Limit exceeded
☑ download.expired - Link expired
☐ download.revoked - Access revoked

File events:

☐ file.uploaded - New file added
☐ file.updated - File modified
☐ file.deleted - File removed

Email events:

☐ email.sent - Email sent
☐ email.delivered - Email delivered
☐ email.opened - Email opened
☐ email.clicked - Link clicked
☐ email.bounced - Email bounced

Webhook Payload

Example webhook payload:

Order created:

{
  "event": "order.created",
  "timestamp": "2024-01-15T15:30:00Z",
  "shop": "yourshop.myshopify.com",
  "data": {
    "order_id": "1045",
    "customer": {
      "id": "12345",
      "email": "customer@example.com",
      "name": "John Smith"
    },
    "products": [
      {
        "id": "67890",
        "name": "Complete Course Bundle",
        "files": ["file_1.pdf", "file_2.pdf"],
        "quantity": 1,
        "price": "49.99"
      }
    ],
    "total": "49.99",
    "currency": "USD",
    "fraud_status": "pending"
  },
  "signature": "abc123..."
}

Webhook Verification

Verify webhook authenticity:

HMAC signature verification:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('base64');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(hmac)
  );
}

// Usage
const isValid = verifyWebhook(
  req.body,
  req.headers['x-alva-hmac-sha256'],
  process.env.WEBHOOK_SECRET
);

Webhook secret:

Settings → Advanced → Webhooks → Webhook Secret
Secret: ws_abc123def456...
[Regenerate Secret]

Store: Securely in environment variables
Use: Verify all webhook requests

Webhook Logs

Monitor webhook delivery:

View logs:

Settings → Advanced → Webhooks → Logs

Columns:
• Timestamp
• Event type
• Endpoint URL
• HTTP status
• Response time
• Retry count
• Error message (if failed)

Filter:
☐ Failed only
☐ Last 24 hours
☐ Specific event type

Debugging:

Click log entry → View details:
• Request headers
• Request payload
• Response headers
• Response body
• Error details
• Retry history

Custom Code

Custom JavaScript

Add custom client-side code:

Inject JavaScript:

Settings → Advanced → Custom Code → JavaScript

// Custom tracking
window.alvaDownload = function(fileId, fileName) {
  // Google Analytics
  if (window.gtag) {
    gtag('event', 'file_download', {
      'event_category': 'Downloads',
      'event_label': fileName,
      'value': 1
    });
  }

  // Facebook Pixel
  if (window.fbq) {
    fbq('track', 'Download', {
      content_name: fileName,
      content_ids: [fileId]
    });
  }

  // Custom analytics
  fetch('/api/analytics/track', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      event: 'download',
      file_id: fileId,
      file_name: fileName
    })
  });
};

Injection points:

○ Download page header
● Download page footer
○ Email templates
○ Thank you page extension

Custom CSS

Style customization:

Advanced CSS:

Settings → Advanced → Custom Code → CSS

/* Custom download page styling */
.alva-download-page {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  min-height: 100vh;
  padding: 40px 20px;
}

.alva-download-container {
  background: white;
  border-radius: 16px;
  box-shadow: 0 20px 60px rgba(0,0,0,0.3);
  max-width: 800px;
  margin: 0 auto;
  padding: 40px;
}

/* Animated download button */
.alva-download-btn {
  position: relative;
  overflow: hidden;
  transition: all 0.3s ease;
}

.alva-download-btn::before {
  content: '';
  position: absolute;
  top: 50%;
  left: 50%;
  width: 0;
  height: 0;
  border-radius: 50%;
  background: rgba(255,255,255,0.3);
  transform: translate(-50%, -50%);
  transition: width 0.6s, height 0.6s;
}

.alva-download-btn:hover::before {
  width: 300px;
  height: 300px;
}

/* Mobile responsive */
@media (max-width: 768px) {
  .alva-download-container {
    padding: 20px;
    border-radius: 8px;
  }
}

Liquid Templates (Advanced)

Custom Liquid templates:

Download page template:

Settings → Advanced → Custom Code → Templates

{% comment %}
  Custom download page template
  Variables available:
  - order
  - customer
  - files
  - download_link
{% endcomment %}

<div class="custom-download-page">
  <header class="download-header">
    {% if shop.logo %}
      <img src="{{ shop.logo }}" alt="{{ shop.name }}">
    {% endif %}
    <h1>{{ 'downloads.welcome' | t: name: customer.first_name }}</h1>
  </header>

  <section class="order-info">
    <h2>{{ 'downloads.order' | t }} #{{ order.number }}</h2>
    <p>{{ 'downloads.date' | t }}: {{ order.created_at | date: '%B %d, %Y' }}</p>
  </section>

  <section class="files-list">
    <h2>{{ 'downloads.files' | t }} ({{ files.size }})</h2>

    {% for file in files %}
      <div class="file-item">
        <div class="file-icon">
          {% include 'file-icon', type: file.type %}
        </div>
        <div class="file-info">
          <h3>{{ file.name }}</h3>
          <p>{{ file.size | file_size }}</p>
        </div>
        <a href="{{ file.download_url }}"
           class="download-btn"
           data-file-id="{{ file.id }}">
          {{ 'downloads.button' | t }}
        </a>
      </div>
    {% endfor %}
  </section>

  <footer class="download-footer">
    <p>{{ 'downloads.expiry' | t: days: download.days_until_expiry }}</p>
    <p>{{ 'downloads.limit' | t: used: download.used, total: download.limit }}</p>
  </footer>
</div>

Developer Tools

Debug Mode

Enable debugging:

Debug mode:

Settings → Advanced → Developer Tools → Debug Mode
☐ Enable debug mode

Warning: ⚠️ Development only, not for production

When enabled:
• Verbose logging
• Detailed error messages
• API request/response logs
• Performance metrics
• No email sending (test mode)
• Test data indicators

Debug console:

[Open Debug Console]
Shows real-time:
• API calls
• Webhook deliveries
• Email attempts
• File operations
• Error stack traces

Request Inspector

Inspect API requests:

Request logs:

Settings → Advanced → Developer Tools → Request Inspector

Recent requests:
| Time     | Method | Endpoint          | Status | Duration |
|----------|--------|-------------------|--------|----------|
| 15:30:12 | GET    | /api/files        | 200    | 45ms     |
| 15:30:08 | POST   | /api/downloads    | 201    | 120ms    |
| 15:29:55 | GET    | /api/orders/1045  | 200    | 30ms     |

Click to view:
• Full request headers
• Request body
• Response headers
• Response body
• Error details

API Testing

Test API endpoints:

API explorer:

Settings → Advanced → Developer Tools → API Explorer

Interactive testing:
1. Select endpoint
2. Fill parameters
3. Add headers (auto-includes auth)
4. Execute request
5. View response

Example:
GET /api/files
Authorization: Bearer ak_live_...

Response:
{
  "files": [...],
  "total": 247,
  "page": 1
}

Performance Tuning

Caching Configuration

Advanced caching:

Cache settings:

Settings → Advanced → Performance → Caching

File caching:
Duration: 24 hours
Storage: CDN edge locations
Invalidation: Automatic on update

Page caching:
Duration: 1 hour
Exclude: Dynamic content
Vary: By customer, order

Database caching:
Query cache: ☑ Enabled
Duration: 5 minutes
Size: 100 MB

Cache control:

[Purge All Caches]
[Purge File Cache]
[Purge Page Cache]
[Purge Database Cache]

Last purge: Jan 15, 2024, 2:30 PM
Cache hit rate: 85%

Database Optimization

Database performance:

Query optimization:

Settings → Advanced → Performance → Database

☑ Enable query caching
☑ Use read replicas (Enterprise)
☑ Auto-index frequently queried fields
☑ Vacuum database weekly

Connection pooling:
Min connections: 5
Max connections: 20
Idle timeout: 10 minutes

Maintenance:

[Analyze Database]
[Vacuum Database]
[Rebuild Indexes]
[View Slow Queries]

Last maintenance: Jan 14, 2024
Database size: 2.4 GB

CDN Configuration

Advanced CDN settings:

CDN optimization:

Settings → Advanced → Performance → CDN

Provider: Cloudflare
Regions: Global (275+ locations)

Features:
☑ Brotli compression
☑ HTTP/2
☑ HTTP/3 (QUIC)
☑ IPv6
☑ Early Hints
☑ Auto-minify CSS/JS

Cache policies:
Static files: 1 year
Downloads: 1 hour (presigned URLs)
Pages: 1 hour

Experimental Features

Beta Features

Try new features:

Available beta features:

Settings → Advanced → Experimental Features

☐ AI-powered file categorization
  Status: Beta
  Description: Automatically categorize uploaded files
  Stability: 90%

☐ Advanced analytics dashboard
  Status: Alpha
  Description: Enhanced reporting and insights
  Stability: 70%

☐ Video streaming optimization
  Status: Beta
  Description: Adaptive bitrate streaming
  Stability: 85%

⚠️ Beta features may change or be removed
✓ Feedback appreciated

Feature Flags

Enable/disable features:

Feature toggles:

Settings → Advanced → Feature Flags

☑ Email notifications - STABLE
☑ Fraud prevention - STABLE
☑ Download page customization - STABLE
☐ Watermarking (PDF) - BETA
☐ ZIP streaming - EXPERIMENTAL
☐ GraphQL API - COMING SOON

Purpose: Gradual rollout, A/B testing, instant rollback

Data Export and Backup

Advanced Export

Export configuration:

Database export:

Settings → Advanced → Data Export

Export options:
☑ All orders
☑ All files metadata
☑ All customer data
☑ All download logs
☑ All email logs
☑ All settings

Format: JSON / CSV / SQL
Encryption: ☑ AES-256
Password: [Required for encryption]

[Export Data]
Size estimate: 450 MB
Time estimate: 2-3 minutes

Automated Backups

Backup configuration:

Backup schedule:

Settings → Advanced → Backups

Automatic backups:
☑ Enable automatic backups
Frequency: Daily at 2:00 AM (shop timezone)
Retention: 30 days
Storage: Offsite (S3-compatible)

Backup includes:
☑ Database (orders, customers, settings)
☑ File metadata (not actual files)
☑ Configuration
☑ Custom code

Backup excludes:
☐ Actual files (use cloud storage backup)
☐ Email logs (separate retention)

Manual backup:

[Create Backup Now]
Last backup: Jan 15, 2024, 2:00 AM
Status: ✓ Successful
Size: 125 MB
[Download] [Restore]

Security Settings

API Security

Advanced security:

IP whitelist:

Settings → Advanced → Security → API Access

☐ Restrict API access to specific IPs
Allowed IPs:
• 192.168.1.100 (Office)
• 10.0.0.5 (Server)

Apply to:
☑ API endpoints
☑ Webhook endpoints
☐ Download endpoints

Webhook Security

Webhook authentication:

Security options:

Settings → Advanced → Security → Webhooks

☑ Require HMAC signature
☑ Require HTTPS
☑ Verify SSL certificates
☐ Use mutual TLS (mTLS)

Replay protection:
☑ Timestamp validation
Tolerance: 5 minutes

IP restrictions:
☐ Limit to specific IPs

Monitoring and Alerts

Performance Monitoring

Monitor app performance:

Performance metrics:

Settings → Advanced → Monitoring

Real-time metrics:
• API response time: 45ms avg
• Download speed: 25 MB/s avg
• Database query time: 8ms avg
• Cache hit rate: 85%
• Error rate: 0.05%

Alerts:
☑ Alert if response time > 500ms
☑ Alert if error rate > 1%
☑ Alert if cache hit < 70%

Error Tracking

Track and fix errors:

Error monitoring:

Settings → Advanced → Monitoring → Errors

Recent errors:
| Time     | Type          | Message           | Count | Status |
|----------|---------------|-------------------|-------|--------|
| 15:30:00 | API           | Rate limit hit    | 1     | Fixed  |
| 14:20:15 | Download      | Token expired     | 3     | Normal |
| 12:45:30 | Email         | SMTP timeout      | 1     | Fixed  |

Click to view:
• Stack trace
• Request details
• User impact
• Resolution steps

Integrations:

☐ Sentry integration
☐ Bugsnag integration
☐ Custom error webhook

GraphQL API (Beta)

GraphQL Configuration

Enable GraphQL:

GraphQL endpoint:

Settings → Advanced → GraphQL (Beta)

☐ Enable GraphQL API
Endpoint: https://yourshop.com/api/graphql
Playground: https://yourshop.com/api/graphql/playground

Authentication: Bearer token (same as REST API)
Rate limit: Shared with REST API

Example query:

query GetOrder($orderNumber: String!) {
  order(number: $orderNumber) {
    id
    number
    createdAt
    customer {
      id
      name
      email
    }
    files {
      id
      name
      size
      downloadUrl
    }
    downloads {
      count
      limit
      expiryDate
    }
  }
}

Best Practices

1. Secure API Keys

Security:

✓ Store in environment variables
✓ Never commit to version control
✓ Rotate regularly (every 90 days)
✓ Use different keys for dev/prod
✓ Revoke immediately if compromised

2. Validate Webhooks

Always verify:

✓ Check HMAC signature
✓ Validate timestamp (prevent replay)
✓ Verify payload structure
✓ Log all webhook attempts
✓ Handle retries properly

3. Handle Rate Limits

Rate limit handling:

// Check rate limit headers
const remaining = response.headers['x-ratelimit-remaining'];
const reset = response.headers['x-ratelimit-reset'];

if (remaining < 10) {
  // Slow down requests
  await sleep(1000);
}

// Handle 429 responses
if (response.status === 429) {
  const retryAfter = response.headers['retry-after'];
  await sleep(retryAfter * 1000);
  // Retry request
}

4. Use Webhooks for Real-Time

Prefer webhooks:

✓ Real-time updates
✓ No polling needed
✓ Efficient use of API quota
✓ Better user experience

vs. Polling (avoid):
❌ Wastes API calls
❌ Delayed updates
❌ Inefficient

5. Monitor and Debug

Production monitoring:

✓ Set up error tracking
✓ Monitor performance metrics
✓ Configure alerts
✓ Review logs regularly
✓ Test integrations thoroughly

Troubleshooting

API Requests Failing

Check:

1. API key valid and not expired
2. Correct authentication header
3. Rate limit not exceeded
4. Endpoint URL correct
5. Request payload valid

Test:

curl -H "Authorization: Bearer {key}" \
  https://yourshop.com/api/health

Expected: 200 OK

Webhooks Not Received

Debug:

1. Check webhook logs for delivery attempts
2. Verify endpoint URL accessible
3. Check HTTPS certificate valid
4. Test webhook endpoint manually
5. Review firewall/IP restrictions

Performance Issues

Optimize:

1. Enable caching
2. Use CDN for file delivery
3. Optimize database queries
4. Check rate limits
5. Review error logs

Next Steps

General Settings Overview - Basic settings
Shop Settings and Preferences - Shop configuration
Email Settings Configuration - Email setup