ackify/docs/en/features/embedding.md

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:

<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:

   <link rel="alternate" type="application/json+oembed"
         href="https://sign.company.com/oembed?url=..." />
   

3. Editor calls /oembed and receives:

   {
     "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:

<!-- 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:

   ![Sign now](https://sign.company.com/badge/policy_2025.png)
   

3. Option 3 - Google Sites:

   • Create a Google Sites page
   • Insert iframe
   • Link from Google Docs

See docs/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

[![Sign this document](https://sign.company.com/badge/policy_2025.png)](https://sign.company.com/?doc=policy_2025)

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

GET /oembed?url=https://sign.company.com/?doc=policy_2025

Response:

{
  "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:

<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:

@media (prefers-color-scheme: dark) {
  /* Automatic dark theme */
}

Custom Size

<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/ - Google Workspace integration
• More examples coming...