Skip to content

Commit 845b0cf

Browse files
erik-svDeveloper
erik-sv
and
Developer
authored
Encypher RTD Provider: module documentation (#6545)
* docs: add Encypher RTD provider documentation Documentation for the Encypher C2PA Content Provenance RTD module. Companion PR to prebid/Prebid.js#14807. * docs(encypherRtd): update privacy section for consent gate and timeout * fix(encypherRtd): fix YAML frontmatter and table formatting for markdownlint - Fix frontmatter delimiters (--- not -) - Use spaced table separator rows (| --- |) - Use dash for unordered lists --------- Co-authored-by: Developer <developer@prebid.org>
1 parent 4d6ab0d commit 845b0cf

1 file changed

Lines changed: 154 additions & 0 deletions

File tree

‎dev-docs/modules/encypherRtdProvider.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
layout: page_v2
3+
title: Encypher Real Time Data Provider
4+
display_name: Encypher C2PA Content Provenance
5+
description: Injects C2PA content provenance signals into OpenRTB bid requests
6+
page_type: module
7+
module_type: rtd
8+
module_code: encypherRtdProvider
9+
enable_download: true
10+
vendor_specific: true
11+
sidebarType: 1
12+
---
13+
14+
# Encypher RTD Provider
15+
{:.no_toc}
16+
17+
- TOC
18+
{:toc}
19+
20+
## Description
21+
22+
The Encypher RTD provider injects [C2PA](https://c2pa.org/) content provenance signals into OpenRTB bid requests at `site.ext.data.c2pa`. This gives DSPs a cryptographic content-integrity signal they can use for brand safety and inventory quality decisioning.
23+
24+
The module detects whether article content already carries embedded provenance markers (from a CMS plugin, CDN worker, or direct API integration) and verifies them server-side. If no existing provenance is found, it signs the content via the Encypher public API. In both cases the result is injected into the bid request.
25+
26+
No external JavaScript is loaded. The module uses only Prebid.js core imports. Every code path calls `callback()`. The module never blocks an auction.
27+
28+
Contact [engineering@encypher.com](mailto:engineering@encypher.com) for more information.
29+
30+
## Integration
31+
32+
Compile the Encypher RTD module into your Prebid build:
33+
34+
```bash
35+
gulp build -modules=rtdModule,encypherRtdProvider
36+
```
37+
38+
## Configuration
39+
40+
Add the Encypher RTD provider to your Prebid config:
41+
42+
```javascript
43+
pbjs.setConfig({
44+
realTimeData: {
45+
auctionDelay: 300,
46+
dataProviders: [{
47+
name: 'encypher',
48+
waitForIt: true,
49+
params: {
50+
// All optional. Free tier works with zero config.
51+
}
52+
}]
53+
}
54+
});
55+
```
56+
57+
### Parameters
58+
59+
{: .table .table-bordered .table-striped }
60+
61+
| Name | Scope | Type | Description |
62+
| - | - | - | - |
63+
| `name` | Required | String | Must be `'encypher'` |
64+
| `waitForIt` | Optional | Boolean | Set to `true` to delay the auction until provenance data is available. Default: `false` |
65+
| `params` | Optional | Object | Configuration parameters (see below) |
66+
| `params.apiBase` | Optional | String | Override the API base URL (default: `https://api.encypher.com`). Useful for staging or development environments. |
67+
| `params.manifestUrl` | Optional | String | Manual manifest URL. When set, the module fetches this URL directly instead of calling the signing API. |
68+
69+
## How It Works
70+
71+
The module runs once per page load through three paths in strict priority:
72+
73+
### Path A: Manifest Shortcut
74+
75+
If a `<meta name="c2pa-manifest-url">` tag or `params.manifestUrl` is present, the module fetches the manifest directly without calling the signing API.
76+
77+
### Path B: Cache
78+
79+
If provenance data for the current page exists in localStorage (30-day TTL, keyed by canonical URL hash), it is served immediately with no network call.
80+
81+
### Path C: API Signing and Verification
82+
83+
The module extracts article text from the DOM and sends it to the Encypher API. The API detects whether the content already contains embedded C2PA provenance markers:
84+
85+
- **If markers are present:** The API verifies them and returns the existing provenance data, including the original signer tier. No signing quota is consumed.
86+
- **If no markers are found:** The API signs the content fresh and returns a new manifest.
87+
88+
The result is cached in localStorage and injected into the bid request.
89+
90+
## Content Extraction
91+
92+
Article text is extracted from the DOM in this priority order:
93+
94+
1. **JSON-LD structured data:** `application/ld+json` scripts containing schema.org `Article`, `NewsArticle`, `BlogPosting`, or `Report` types.
95+
2. **`<article>` element:** `textContent` of the first `<article>` element.
96+
3. **`[role="main"]` element:** `textContent` of the first element with `role="main"`.
97+
98+
Content shorter than 50 characters is skipped. Content longer than 50,000 characters is truncated.
99+
100+
## Data Injected
101+
102+
The following object is placed at `ortb2Fragments.global.site.ext.data.c2pa`:
103+
104+
```json
105+
{
106+
"manifest_url": "https://api.encypher.com/api/v1/public/prebid/manifest/abc123",
107+
"verified": true,
108+
"signer_tier": "connected",
109+
"signed_at": "2026-04-01T10:00:00Z",
110+
"content_hash": "a1b2c3d4e5f6",
111+
"source": "auto",
112+
"extraction_method": "json-ld"
113+
}
114+
```
115+
116+
{: .table .table-bordered .table-striped }
117+
118+
| Field | Type | Description |
119+
| - | - | - |
120+
| `manifest_url` | String | URL to retrieve the C2PA manifest |
121+
| `verified` | Boolean | `true` if provenance was successfully verified or signed |
122+
| `signer_tier` | String | Signing identity tier (see table below) |
123+
| `signed_at` | String | ISO 8601 timestamp of signing |
124+
| `content_hash` | String | SHA-256 hash of article text |
125+
| `source` | String | How provenance was obtained: `cms`, `cache`, or `auto` |
126+
| `extraction_method` | String | DOM extraction method: `json-ld`, `article-element`, or `role-main` |
127+
128+
## Signer Tiers
129+
130+
The `signer_tier` field tells DSPs how the content was authenticated:
131+
132+
{: .table .table-bordered .table-striped }
133+
134+
| Tier | Meaning |
135+
| - | - |
136+
| `byok` | Publisher signed with their own key (strongest identity) |
137+
| `connected` | Publisher authenticated with Encypher and signed at publish time |
138+
| `encypher_free` | Content was auto-signed by Encypher at first pageview (no publisher authentication) |
139+
| `local` | Manifest fetched from a local or self-hosted endpoint |
140+
141+
DSPs can use this field for differential bidding. Content signed by authenticated publishers carries stronger brand-safety guarantees than content attested by a third party at pageview time.
142+
143+
## Free Tier
144+
145+
The free tier provides 1,000 unique content signatures per publisher domain per month. Re-requests for the same content (deduped by content hash) do not count against quota. Verification of already-signed content does not count against quota. When the quota is exceeded, the module continues without injecting provenance data (fail-open).
146+
147+
## Privacy
148+
149+
The module uses Prebid's `getStorageManager` for localStorage access, which enforces GDPR/TCF consent. If consent is denied, caching is disabled and Path C (auto-sign) is skipped entirely, so no page content leaves the browser. When consent is granted but caching is unavailable, the module falls back to API calls on each page load. Article text sent to the Encypher API for signing is not stored on Encypher's servers. Only content hashes and metadata are persisted. A 2-second timeout ensures the module never blocks the auction.
150+
151+
## Further Reading
152+
153+
- [C2PA Specification](https://c2pa.org/specifications/)
154+
- [Encypher Documentation](https://encypher.com/docs)

0 commit comments

Comments
 (0)