Integration Guide

Step-by-step guide to embedding Decipon badges on your website.

1. Register as a Publisher

Use your existing Decipon API key to create a publisher account:

curl -X POST https://api.decipon.com/publishers/register \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Publisher"}'

Response:

{
  "publisher_id": "a1b2c3d4-...",
  "name": "My Publisher",
  "token": "pub_abc123...",
  "message": "Save this token — it cannot be retrieved again."
}

Save both the pub_ token (for API authentication) and the publisher_id (for the embed widget). The token cannot be retrieved again.

2. Add & Verify Your Domain

2a. Add a domain

curl -X POST https://api.decipon.com/publishers/domains \
  -H "X-Publisher-Token: pub_your-token" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "method": "dns"}'

Response:

{
  "domain_id": "d5e6f7a8-...",
  "domain": "example.com",
  "method": "dns",
  "verification_token": "abc123def456...",
  "instructions": "Add a TXT record to your DNS: ..."
}

2b. Place the verification token

Follow the instructions for your chosen method:

DNS TXT Record

Add a TXT record to your DNS:


                            Host: _decipon-verify.example.com

                            Value: decipon-verify={your-verification-token}

HTML Meta Tag

Add this tag to the <head> of your homepage:


                            <meta name="decipon-verify" content="{your-verification-token}">

.well-known File

Create the file /.well-known/decipon-verify.txt with:


                            decipon-verify={your-verification-token}

2c. Trigger verification

curl -X POST https://api.decipon.com/publishers/domains/verify \
  -H "X-Publisher-Token: pub_your-token" \
  -H "Content-Type: application/json" \
  -d '{"domain_id": "d5e6f7a8-..."}'

Use the domain_id returned in step 2a. Domains are re-verified automatically every 7 days.

3. Embed the Badge

Add this snippet wherever you want to display a badge. Replace sha256:... with the content hash from your analysis, and your-publisher-id with the publisher_id from step 1.

<!-- Decipon Badge -->
<div data-decipon-hash="sha256:..."
     data-decipon-token="your-publisher-id"></div>
<script src="https://api.decipon.com/static/js/decipon-widget.v1.js"
        async defer></script>

Note

The data-decipon-token attribute takes your publisher ID (UUID), not the pub_ API token. Your publisher ID is returned in the registration response and is also visible on your dashboard.

4. Generate Embed Code (Optional)

You can also retrieve a pre-filled embed snippet via the API:

curl https://api.decipon.com/publishers/embed-code \
  -H "X-Publisher-Token: pub_your-token"

Returns a ready-to-use HTML snippet with your publisher ID pre-filled. Just replace the content hash placeholder.

FAQ

How often are domains re-verified?

Every 7 days. If verification fails, there's a 48-hour grace period before the domain is deactivated.

Does the widget affect page load speed?

The widget is under 5KB gzipped, loads asynchronously, uses IntersectionObserver for lazy loading, and creates zero layout shift. It uses system fonts and never loads external resources.

What analytics are collected?

Badge impressions and clicks are counted per content hash per hour. Embedding domain is recorded (domain only, no path). No cookies, no tracking pixels, no personally identifiable information is stored.

What is the difference between my publisher token and publisher ID?

Your publisher token (pub_...) is a secret used for API authentication — never expose it in client-side code. Your publisher ID (UUID) is a public identifier used in the embed widget's data-decipon-token attribute.

API Quick Reference

Publisher endpoints used during onboarding and management. For the complete API reference with request/response schemas, see the interactive API documentation.

Endpoint	Method	Auth	Description
/publishers/register	POST	API Key	Create publisher account
/publishers/domains	POST	Publisher Token	Add domain for verification
/publishers/domains/verify	POST	Publisher Token	Trigger domain verification
/publishers/domains/{id}	DELETE	Publisher Token	Remove a domain
/publishers/embed-code	GET	Publisher Token	Get pre-filled embed snippet
/publishers/api/analytics	GET	Publisher Token	Analytics data (JSON)