Parâmetros de conversão em URLs

Um visitante que assiste ao vídeo e depois compra faz isso em outra página — um checkout, um formulário, uma página de obrigado. Nada nessa segunda página sabe o que aconteceu no player, a menos que você leve a informação junto. Estas três peças da API existem para isso.

conversionKey

A propriedade que identifica a visualização atual: a sessão, o player e a variante, quanto foi assistido e quais variantes de recurso estavam ativas. É o valor que o resto desta página movimenta.

urlUpdater

Recebe uma URL e devolve com os parâmetros de conversão e rastreamento anexados. Use quando sua página monta o link de destino:

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  const url = player.urlUpdater("https://example.com/checkout");

  // https://example.com/checkout?<conversion and tracking params>
  console.log(url);
});

injectUrlUpdater

Registra uma função que reescreve toda URL que o player aponta — botões de chamada para ação, âncoras, imagens. Use quando os links estão dentro do player, e não na sua marcação:

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.injectUrlUpdater((url, element) => {
    const next = new URL(url, window.location.href);

    next.searchParams.set("utm_source", "player");

    return next.toString();
  });
});

A função recebe a URL original e, quando existe, o elemento a que ela pertence, então dá para tratar um CTA de forma diferente de uma imagem.

Como escolher entre os dois

Use o urlUpdater quando o link é do seu código, e o injectUrlUpdater quando é do player. Não são alternativas um ao outro, e sim duas metades do mesmo trabalho — páginas com um CTA próprio e chamadas para ação do player costumam precisar dos dois.