Skip to content

Security & Privacy ​

Best practices for securely embedding AddMaple widgets.

Key Principles ​

  1. No credentials in the browser — getData() must be server-backed
  2. Short-lived URLs — serverFetch URLs should expire quickly
  3. Sanitize preview data — Remove PII unless explicitly consented
  4. User consent — Inform users before server-mode analysis

No Partner Keys in Browser ​

Never Do This

js
// ❌ WRONG - credentials exposed in browser
async function getData() {
  return fetch('https://thirdparty.example.com/api/v1/data', {
    headers: { 'Authorization': 'Bearer MY_SECRET_API_KEY' }
  })
}

Do This Instead

js
// ✅ CORRECT - call your own server
async function getData() {
  return fetch('/api/addmaple/get-embed-data', {
    credentials: 'include' // Uses session auth
  }).then(r => r.json())
}

Preview Row Sanitization ​

Preview rows are processed in the browser. Consider what data is appropriate:

js
function sanitizePreviewRows(rows) {
  return rows.map(row => ({
    ...row,
    // Remove or mask PII
    email: undefined,
    name: undefined,
    phone: undefined,
    // Keep analysis-relevant fields
    satisfaction: row.satisfaction,
    age_group: row.age_group,
    comment: row.comment
  }))
}

What to Include ​

IncludeExclude (unless consented)
Survey responsesEmail addresses
Numeric scoresFull names
CategoriesPhone numbers
Anonymized textPhysical addresses
Age groupsIP addresses

Secure serverFetch URLs ​

When providing serverFetch for server-mode analysis:

js
// Generate S3 presigned URL - expires in 15 minutes
const serverFetch = {
  url: await s3.getSignedUrl('getObject', {
    Bucket: 'my-bucket',
    Key: `data/${datasetId}.csv`,
    Expires: 900
  }),
  method: 'GET',
  expiresAt: new Date(Date.now() + 900000).toISOString()
}

Option 2: Partner Endpoint with IP Allowlist ​

Register your endpoint with AddMaple and only allow AddMaple IPs:

js
// POST /partners/v1/data-endpoints
{
  "datasetId": "tf_123",
  "url": "https://partner.example.com/addmaple/full-data/tf_123",
  "auth": { "type": "bearer", "secretHint": "access-key-hint" },
  "allowedIps": ["52.4.12.34", "52.4.12.35"]
}

Option 3: Short-Lived Tokens ​

Generate a token that expires and can only be used once:

js
const serverFetch = {
  url: `https://api.example.com/data/${datasetId}`,
  headers: {
    'X-AddMaple-Token': generateOneTimeToken(datasetId, '15m')
  },
  expiresAt: new Date(Date.now() + 900000).toISOString()
}

The embed shows a consent dialog before server-mode analysis or AI Chat that requires full data upload.

  1. User requests server-mode analysis
  2. Embed shows consent dialog explaining data will be processed server-side
  3. User confirms or declines
  4. If confirmed, embed calls serverFetch.url
  5. Analytics event emitted: consent_granted or consent_declined

You can pre-consent users if they've already agreed to your terms:

jsx
<AddMapleEmbed
  getData={getData}
  datasetId="tf_123"
  userId="user_456"
  widgetType="keyDrivers"
  onAnalyticsEvent={handleAnalytics}
  // User has already consented to data processing
  preConsented={true}
/>

Data Retention ​

AddMaple's data handling for server-mode analysis:

DataRetention
Full dataset (from serverFetch)Ephemeral — deleted after analysis
Analysis resultsCached up to 24 hours
Aggregated metricsRetained for analytics
PIINever stored — must be excluded

Enterprise Options

Enterprise customers can configure:

  • Custom data retention policies
  • Private processing environments
  • Audit logging

Contact [email protected] for details.

Security Checklist ​

  • [ ] getData() calls your own server, not third-party APIs directly
  • [ ] No API keys or secrets in browser-side code
  • [ ] Preview rows are sanitized (PII removed)
  • [ ] serverFetch URLs expire within 15-60 minutes
  • [ ] serverFetch URLs are protected (presigned or IP-allowed)
  • [ ] Users are informed about server-mode data processing
  • [ ] Analytics events are monitored for security issues

Partner Documentation