Appearance
Security & Privacy
Best practices for securely embedding AddMaple widgets.
Key Principles
- No credentials in the browser —
getData()must be server-backed - Short-lived URLs —
serverFetchURLs should expire quickly - Sanitize preview data — Remove PII unless explicitly consented
- 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' }
})
}1
2
3
4
5
6
2
3
4
5
6
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())
}1
2
3
4
5
6
2
3
4
5
6
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
}))
}1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
What to Include
| Include | Exclude (unless consented) |
|---|---|
| Survey responses | Email addresses |
| Numeric scores | Full names |
| Categories | Phone numbers |
| Anonymized text | Physical addresses |
| Age groups | IP addresses |
Secure serverFetch URLs
When providing serverFetch for server-mode analysis:
Option 1: Presigned URLs (Recommended)
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()
}1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
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"]
}1
2
3
4
5
6
7
2
3
4
5
6
7
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()
}1
2
3
4
5
6
7
2
3
4
5
6
7
User Consent
The embed shows a consent dialog before server-mode analysis or AI Chat that requires full data upload.
Consent Flow
- User requests server-mode analysis
- Embed shows consent dialog explaining data will be processed server-side
- User confirms or declines
- If confirmed, embed calls
serverFetch.url - Analytics event emitted:
consent_grantedorconsent_declined
Customizing Consent
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}
/>1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
Data Retention
AddMaple's data handling for server-mode analysis:
| Data | Retention |
|---|---|
| Full dataset (from serverFetch) | Ephemeral — deleted after analysis |
| Analysis results | Cached up to 24 hours |
| Aggregated metrics | Retained for analytics |
| PII | Never 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)
- [ ]
serverFetchURLs expire within 15-60 minutes - [ ]
serverFetchURLs are protected (presigned or IP-allowed) - [ ] Users are informed about server-mode data processing
- [ ] Analytics events are monitored for security issues