Snippet reference
The embed snippet is a single <script> tag. Everything the loader needs is expressed as
data-pc-* attributes on that tag.
<script
src="https://sdk.percus.video/embed/smartEmbed.js"
data-pc-channel-handle="pc_xxxxxxxxxx"
data-pc-api-key="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
></script>
Those two attributes are the only required ones. Everything else has a default.
Required
| Attribute | Purpose |
|---|---|
data-pc-channel-handle | The channel to play (pc_…). Missing → the loader throws MISSING_CHANNEL_HANDLE |
data-pc-api-key | Public API key for the channel (pk_…). Missing → the loader throws MISSING_API_KEY |
The API key is public by design: it identifies the channel and is safe to place in a page that recipients can view. It does not grant access to the backoffice.
Personalization
There are three ways to get personalization data into the video. They are mutually exclusive — pick one per embed.
| Attribute | Model | Where the data lives |
|---|---|---|
data-pc-data | Inline | In the snippet itself |
data-pc-data-url | Client-hosted | Fetched by the player from your own endpoint at view time |
data-pc-viewer-token | Percus-hosted | Uploaded to Percus in advance, fetched per view |
See Data Handling for the security properties of each.
data-pc-viewer-token
An opaque per-recipient token that you choose. The loader mints a short-lived embed-session token against the Campaign API and then reads the matching personalization object from the Render Data service.
This path is best-effort by design: if the token is absent, the mint fails, the read
fails, or the response does not parse, the loader degrades to null and the video still
plays with whatever personalization the channel config carries. A missing token costs
nothing — with no viewer token the loader makes zero extra calls.
When data-pc-data-url is present, hosted render data is skipped entirely, because the
player would discard it.
| Attribute | Default | Purpose |
|---|---|---|
data-pc-viewer-token-param | pcvt | Read the viewer token from this URL query parameter instead of the attribute |
data-pc-keep-viewer-token-param | false | By default the token is stripped from the page URL via history.replaceState once read. Set truthy to keep it |
A value in the URL parameter that is not a well-formed viewer token is left in place and ignored — it may belong to your page, and it must never reach the mint endpoint.
Layout
All of these map to CSS on the generated host element.
| Attribute | Default | Purpose |
|---|---|---|
data-pc-width | 100% | Host width |
data-pc-height | auto | Host height |
data-pc-max-width | 100% | Host max width |
data-pc-aspect-ratio | 16 / 9 | Reserves space before the player reports its real ratio, avoiding layout shift |
data-pc-border | 0 | Host border |
The player reports its true aspect ratio once the animation loads; the attribute is the hint used until then.
Playback and mobile
| Attribute | Default | Purpose |
|---|---|---|
data-pc-autoplay | — | Attempt autoplay where the browser permits it |
data-pc-title | — | Accessible title for the embed iframe |
data-pc-mobile-controls-size | normal | large gives bigger tap targets on touch devices |
data-pc-mobile-fullscreen-on-play | false | On touch devices, enter fullscreen when the viewer starts playback |
Locale
| Attribute | Purpose |
|---|---|
data-pc-locale | Select a locale variant of the template. When omitted, the locale is inferred |
Advanced
Most integrations never need these. They exist for multi-environment setups, shared links, and debugging.
| Attribute | Purpose |
|---|---|
data-pc-campaign-api-url | Pin the Campaign API base URL. Setting this opts the embed out of the config CDN, because a pinned API may belong to a different environment — expect a slower config fetch |
data-pc-render-data-api-url | Base URL of the Render Data service. Required for the hosted render-data path; Campaign never learns this URL |
data-pc-sdk-url | Pin a specific SDK bundle instead of the resolved one |
data-pc-resolver-version | v1 pins the legacy no-store resolver. The default (v2) uses the cacheable config path |
data-pc-share-slug | Play a shared video link rather than a channel |
data-pc-embed-session-token | Supply a pre-minted embed-session token |
data-pc-cta-href | Legacy single-CTA embeds only |
data-pc-log-target | CSS selector of an element to receive loader events, for debugging |
data-pc-campaign-api-url has a performance costThe loader ships with a default config CDN. Pinning the campaign API disables it, because the CDN fronts one specific API Gateway and serving another environment's config from it would resolve against the wrong backend. Measured, the config leg goes from ~62 ms to ~491 ms. Only set this if you genuinely need a non-default environment.