mirror of
https://github.com/btouchard/ackify-ce.git
synced 2026-02-28 10:48:47 -06:00
Benjamin
394 lines
8.8 KiB
Markdown
394 lines
8.8 KiB
Markdown
# Embedding & Integrations
|
|
|
|
Integrate Ackify into your tools (Notion, Outline, Google Docs, etc.).
|
|
|
|
## URL Formats: When to Use What
|
|
|
|
Ackify provides two URL formats depending on your use case:
|
|
|
|
### `/?doc=<id>` - Full Page Experience
|
|
|
|
**Use for**:
|
|
- Direct links in emails, chat messages
|
|
- Standalone signature pages
|
|
- When you want full navigation and context
|
|
|
|
**Behavior**:
|
|
- Full page with header, navigation, and footer
|
|
- Optimized for direct user access
|
|
- Complete branding and organization context
|
|
|
|
**Example**:
|
|
```
|
|
https://sign.company.com/?doc=policy_2025
|
|
```
|
|
|
|
### `/embed?doc=<id>` - Embed-Optimized View
|
|
|
|
**Use for**:
|
|
- iFrame embeds in Notion, Outline, Confluence
|
|
- Widget integrations in third-party platforms
|
|
- When you want a clean, minimal interface
|
|
|
|
**Behavior**:
|
|
- Minimal interface without navigation
|
|
- Optimized for small iframe containers
|
|
- Focuses only on signature status and action button
|
|
- No automatic redirects
|
|
|
|
**Example**:
|
|
```
|
|
https://sign.company.com/embed?doc=policy_2025
|
|
```
|
|
|
|
> **Important**: For embedding in Notion/Outline, always use `/embed?doc=...` to avoid unwanted redirections and get the optimal embed experience.
|
|
|
|
## Integration Methods
|
|
|
|
### 1. Direct Link
|
|
|
|
The simplest:
|
|
```
|
|
https://sign.company.com/?doc=policy_2025
|
|
```
|
|
|
|
**Usage**:
|
|
- Email
|
|
- Chat (Slack, Teams)
|
|
- Wiki
|
|
- Documentation
|
|
|
|
**Behavior**:
|
|
- User clicks → Arrives at signature page
|
|
- Logs in via OAuth2
|
|
- Signs the document
|
|
|
|
### 2. iFrame Embed
|
|
|
|
To integrate in a web page:
|
|
|
|
```html
|
|
<iframe src="https://sign.company.com/embed?doc=policy_2025"
|
|
width="600"
|
|
height="200"
|
|
frameborder="0"
|
|
style="border: 1px solid #ddd; border-radius: 6px;">
|
|
</iframe>
|
|
```
|
|
|
|
**Render**:
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ 📄 Security Policy 2025 │
|
|
│ 42 confirmations │
|
|
│ [Sign this document] │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
### 3. oEmbed (Auto-discovery)
|
|
|
|
For platforms supporting oEmbed (Notion, Outline, Confluence, etc.).
|
|
|
|
#### How it works
|
|
|
|
1. Paste URL in your editor:
|
|
```
|
|
https://sign.company.com/?doc=policy_2025
|
|
```
|
|
|
|
2. Editor auto-detects via meta tag:
|
|
```html
|
|
<link rel="alternate" type="application/json+oembed"
|
|
href="https://sign.company.com/oembed?url=..." />
|
|
```
|
|
|
|
3. Editor calls `/oembed` and receives:
|
|
```json
|
|
{
|
|
"type": "rich",
|
|
"version": "1.0",
|
|
"title": "Security Policy 2025 - 42 confirmations",
|
|
"provider_name": "Ackify",
|
|
"html": "<iframe src=\"https://sign.company.com/?doc=policy_2025\" ...>",
|
|
"height": 200
|
|
}
|
|
```
|
|
|
|
4. Editor displays iframe automatically
|
|
|
|
#### Supported Platforms
|
|
|
|
- ✅ **Notion** - Paste URL → Auto-embed
|
|
- ✅ **Outline** - Paste URL → Auto-embed
|
|
- ✅ **Confluence** - oEmbed macro
|
|
- ✅ **AppFlowy** - URL unfurling
|
|
- ✅ **Slack** - Link unfurling (Open Graph)
|
|
- ✅ **Microsoft Teams** - Card preview
|
|
- ✅ **Discord** - Rich embed
|
|
|
|
## Open Graph & Twitter Cards
|
|
|
|
Ackify automatically generates meta tags for previews:
|
|
|
|
```html
|
|
<!-- Auto-generated for /?doc=policy_2025 -->
|
|
<meta property="og:title" content="Security Policy 2025 - 42 confirmations" />
|
|
<meta property="og:description" content="42 people confirmed reading the document" />
|
|
<meta property="og:url" content="https://sign.company.com/?doc=policy_2025" />
|
|
<meta property="og:type" content="website" />
|
|
<meta name="twitter:card" content="summary" />
|
|
```
|
|
|
|
**Result in Slack/Teams**:
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ 🔐 Ackify │
|
|
│ Security Policy 2025 │
|
|
│ 42 confirmations │
|
|
│ sign.company.com │
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
## Specific Integrations
|
|
|
|
### Notion
|
|
|
|
**Method 1: Auto-embed (Recommended)**
|
|
|
|
1. Paste URL in a Notion page:
|
|
```
|
|
https://sign.company.com/embed?doc=policy_2025
|
|
```
|
|
|
|
2. Notion auto-detects oEmbed
|
|
3. Widget appears with signature button
|
|
|
|
**Method 2: Manual embed**
|
|
|
|
1. Type `/embed` in Notion
|
|
2. Paste the embed URL:
|
|
```
|
|
https://sign.company.com/embed?doc=policy_2025
|
|
```
|
|
|
|
> **Tip**: Use `/embed?doc=...` instead of `/?doc=...` to get the optimal embed view without navigation elements.
|
|
|
|
### Outline
|
|
|
|
1. In an Outline document, paste:
|
|
```
|
|
https://sign.company.com/embed?doc=policy_2025
|
|
```
|
|
|
|
2. Outline automatically loads the widget
|
|
|
|
> **Note**: Using `/embed?doc=...` ensures you get the clean widget view without redirects.
|
|
|
|
### Google Docs
|
|
|
|
Google Docs doesn't support iframes directly, but:
|
|
|
|
1. **Option 1 - Link**:
|
|
```
|
|
Please sign: https://sign.company.com/?doc=policy_2025
|
|
```
|
|
|
|
2. **Option 2 - Image Badge**:
|
|
```
|
|
|
|
```
|
|
|
|
3. **Option 3 - Google Sites**:
|
|
- Create a Google Sites page
|
|
- Insert iframe
|
|
- Link from Google Docs
|
|
|
|
See [docs/integrations/google-doc/](../integrations/google-doc/) for more details.
|
|
|
|
### Confluence
|
|
|
|
1. Edit a Confluence page
|
|
2. Insert "oEmbed" or "HTML Embed" macro
|
|
3. Paste:
|
|
```
|
|
https://sign.company.com/embed?doc=policy_2025
|
|
```
|
|
|
|
> **Note**: Use `/embed?doc=...` for the best iframe experience.
|
|
|
|
### Slack
|
|
|
|
**Link Unfurling**:
|
|
|
|
1. Post URL in a channel:
|
|
```
|
|
Hey team, please sign: https://sign.company.com/?doc=policy_2025
|
|
```
|
|
|
|
2. Slack automatically displays preview (Open Graph)
|
|
|
|
**Slash Command** (future):
|
|
```
|
|
/ackify sign policy_2025
|
|
```
|
|
|
|
### Microsoft Teams
|
|
|
|
1. Post URL in a conversation
|
|
2. Teams displays card preview (Open Graph)
|
|
|
|
## PNG Badge
|
|
|
|
Generate a visual badge for README, wiki, etc.
|
|
|
|
### Badge URL
|
|
|
|
```
|
|
https://sign.company.com/badge/policy_2025.png
|
|
```
|
|
|
|
**Render**:
|
|
|
|
|
|
|
|
### Markdown
|
|
|
|
```markdown
|
|
[](https://sign.company.com/?doc=policy_2025)
|
|
```
|
|
|
|
### HTML
|
|
|
|
```html
|
|
<a href="https://sign.company.com/?doc=policy_2025">
|
|
<img src="https://sign.company.com/badge/policy_2025.png" alt="Signature status">
|
|
</a>
|
|
```
|
|
|
|
## oEmbed API
|
|
|
|
### Endpoint
|
|
|
|
```http
|
|
GET /oembed?url=https://sign.company.com/?doc=policy_2025
|
|
```
|
|
|
|
**Response**:
|
|
```json
|
|
{
|
|
"type": "rich",
|
|
"version": "1.0",
|
|
"title": "Document policy_2025 - 42 confirmations",
|
|
"provider_name": "Ackify",
|
|
"provider_url": "https://sign.company.com",
|
|
"html": "<iframe src=\"https://sign.company.com/?doc=policy_2025\" width=\"100%\" height=\"200\" frameborder=\"0\" style=\"border: 1px solid #ddd; border-radius: 6px;\" allowtransparency=\"true\"></iframe>",
|
|
"width": null,
|
|
"height": 200
|
|
}
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Description | Example |
|
|
|-----------|-------------|---------|
|
|
| `url` | Document URL (required) | `?url=https://...` |
|
|
| `maxwidth` | Max width (optional) | `?maxwidth=800` |
|
|
| `maxheight` | Max height (optional) | `?maxheight=300` |
|
|
|
|
### Discovery
|
|
|
|
All pages include discovery tag:
|
|
|
|
```html
|
|
<link rel="alternate"
|
|
type="application/json+oembed"
|
|
href="https://sign.company.com/oembed?url=..."
|
|
title="Document title" />
|
|
```
|
|
|
|
## Customization
|
|
|
|
### Dark Mode Theme
|
|
|
|
Widget automatically detects browser's dark mode:
|
|
|
|
```css
|
|
@media (prefers-color-scheme: dark) {
|
|
/* Automatic dark theme */
|
|
}
|
|
```
|
|
|
|
### Custom Size
|
|
|
|
```html
|
|
<iframe src="https://sign.company.com/?doc=policy_2025"
|
|
width="800"
|
|
height="300"
|
|
frameborder="0">
|
|
</iframe>
|
|
```
|
|
|
|
### Language
|
|
|
|
Widget automatically detects browser language:
|
|
- `fr` - Français
|
|
- `en` - English
|
|
- `es` - Español
|
|
- `de` - Deutsch
|
|
- `it` - Italiano
|
|
|
|
## Security
|
|
|
|
### iFrame Sandboxing
|
|
|
|
By default, Ackify iframes allow:
|
|
- `allow-same-origin` - OAuth2 cookies
|
|
- `allow-scripts` - Vue.js features
|
|
- `allow-forms` - Signature submission
|
|
- `allow-popups` - OAuth redirect
|
|
|
|
### CORS
|
|
|
|
Ackify automatically configures CORS for:
|
|
- All origins (public reading)
|
|
- Credentials via `Access-Control-Allow-Credentials`
|
|
|
|
### CSP
|
|
|
|
Content Security Policy headers configured to allow embedding:
|
|
|
|
```
|
|
X-Frame-Options: SAMEORIGIN
|
|
Content-Security-Policy: frame-ancestors 'self' https://notion.so https://outline.com
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### iframe not displaying
|
|
|
|
Verify:
|
|
- HTTPS enabled (required for OAuth)
|
|
- CSP headers allow embedding
|
|
- No content blocker (uBlock, Privacy Badger)
|
|
|
|
### oEmbed not detected
|
|
|
|
Verify:
|
|
- Tag `<link rel="alternate" type="application/json+oembed">` is present
|
|
- URL is exact (with `?doc=...`)
|
|
- Platform supports oEmbed discovery
|
|
|
|
### Slack preview empty
|
|
|
|
Verify:
|
|
- Open Graph meta tags present
|
|
- URL publicly accessible
|
|
- No infinite redirect
|
|
|
|
## Complete Examples
|
|
|
|
See:
|
|
- [docs/integrations/google-doc/](../integrations/google-doc/) - Google Workspace integration
|
|
- More examples coming...
|