Referencia del snippet

El snippet de embed es una sola etiqueta <script>. Todo lo que el loader necesita se expresa como atributos data-pc-* en esa etiqueta.

<script
  src="https://sdk.percus.video/embed/smartEmbed.js"
  data-pc-channel-handle="pc_xxxxxxxxxx"
  data-pc-api-key="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
></script>

Esos dos atributos son los únicos obligatorios. Todo lo demás tiene un valor por defecto.

Obligatorios

Atributo	Propósito
data-pc-channel-handle	El canal a reproducir (pc_…). Si falta, el loader lanza MISSING_CHANNEL_HANDLE
data-pc-api-key	API key pública del canal (pk_…). Si falta, el loader lanza MISSING_API_KEY

La API key es pública por diseño: identifica al canal y es seguro ponerla en una página que los destinatarios pueden ver. No da acceso al backoffice.

Personalización

Hay tres formas de hacer llegar los datos de personalización al video. Son mutuamente excluyentes — se elige una por embed.

Atributo	Modelo	Dónde viven los datos
data-pc-data	En línea	En el propio snippet
data-pc-data-url	Alojado por el cliente	El player los descarga de tu endpoint al momento de la vista
data-pc-viewer-token	Alojado en Percus	Se cargan por adelantado, se leen por vista

Ver Manejo de datos para las propiedades de seguridad de cada uno.

data-pc-viewer-token

Un token opaco por destinatario que eliges tú. El loader emite un token de sesión de embed de corta duración contra el Campaign API y luego lee el objeto de personalización correspondiente desde el servicio de Render Data.

Este camino es best-effort por diseño: si falta el token, si falla la emisión, si falla la lectura o si la respuesta no parsea, el loader degrada a null y el video igual se reproduce con la personalización que traiga la configuración del canal. Un token ausente no cuesta nada — sin viewer token el loader hace cero llamadas extra.

Cuando está presente data-pc-data-url, el render data alojado se omite por completo, porque el player lo descartaría.

Atributo	Por defecto	Propósito
data-pc-viewer-token-param	pcvt	Leer el viewer token desde este parámetro de la URL en vez del atributo
data-pc-keep-viewer-token-param	false	Por defecto el token se elimina de la URL de la página con history.replaceState al leerlo. Poner un valor verdadero para conservarlo

Un valor en el parámetro de URL que no sea un viewer token bien formado se deja intacto y se ignora — puede pertenecer a tu página, y nunca debe llegar al endpoint de emisión.

Layout

Todos estos se traducen a CSS sobre el elemento anfitrión generado.

Atributo	Por defecto	Propósito
data-pc-width	100%	Ancho del host
data-pc-height	auto	Alto del host
data-pc-max-width	100%	Ancho máximo del host
data-pc-aspect-ratio	16 / 9	Reserva espacio antes de que el player informe su relación real, evitando saltos de layout
data-pc-border	0	Borde del host

El player informa su relación de aspecto real cuando carga la animación; el atributo es la pista que se usa hasta ese momento.

Reproducción y móvil

Atributo	Por defecto	Propósito
data-pc-autoplay	—	Intentar autoplay donde el navegador lo permita
data-pc-title	—	Título accesible para el iframe del embed
data-pc-mobile-controls-size	normal	large da objetivos táctiles más grandes en dispositivos táctiles
data-pc-mobile-fullscreen-on-play	false	En dispositivos táctiles, entrar en pantalla completa cuando el viewer inicia la reproducción

Idioma

Atributo	Propósito
data-pc-locale	Seleccionar una variante de idioma del template. Si se omite, el idioma se infiere

Avanzados

La mayoría de las integraciones nunca los necesita. Existen para configuraciones multi-ambiente, links compartidos y depuración.

Atributo	Propósito
data-pc-campaign-api-url	Fijar la URL base del Campaign API. Fijarla saca al embed del CDN de configuración, porque un API fijado puede pertenecer a otro ambiente — esperar un fetch de configuración más lento
data-pc-render-data-api-url	URL base del servicio de Render Data. Necesaria para el camino de render data alojado; Campaign nunca conoce esta URL
data-pc-sdk-url	Fijar un bundle específico del SDK en vez del resuelto
data-pc-resolver-version	v1 fija el resolver legacy sin caché. El valor por defecto (v2) usa el camino de configuración cacheable
data-pc-share-slug	Reproducir un link de video compartido en vez de un canal
data-pc-embed-session-token	Entregar un token de sesión de embed ya emitido
data-pc-cta-href	Sólo para embeds legacy de un solo CTA
data-pc-log-target	Selector CSS de un elemento que recibirá eventos del loader, para depuración

data-pc-campaign-api-url tiene un costo de rendimiento

El loader trae por defecto un CDN de configuración. Fijar el campaign API lo desactiva, porque el CDN sirve a un API Gateway específico y servir la configuración de otro ambiente desde ahí resolvería contra el backend equivocado. Medido, la pierna de configuración pasa de ~62 ms a ~491 ms. Fijarlo sólo si realmente se necesita un ambiente no predeterminado.