Full SDK (Web)

👍

SDK recomendado

Recomendamos o uso do Web Seamless SDK para uma experiência de integração tranquila. Essa opção oferece uma solução de pagamento flexível com componentes de IU pré-criados e opções de personalização.

Bem-vindo ao guia do Yuno Full Web SDK . Este guia o ajudará a começar a usar as soluções de pagamento da Yuno. Se você deseja implementar sua primeira integração de pagamento ou aprimorar sua configuração existente, este guia fornece todas as informações necessárias para criar uma experiência de pagamento perfeita para seus usuários.

📘

Documentação da versão mais recente

Este guia aborda a versão mais recente do nosso Full Web SDK. Para ler sobre versões anteriores, explore os links relacionados ou visite o changelog.

Escolha seu método de integração

Vamos ajudá-lo a escolher o método de integração que melhor atenda às suas necessidades. Cada abordagem tem vantagens específicas, e a escolha da correta depende de seu ambiente de desenvolvimento, de seus requisitos técnicos e de suas preferências.

• Método 1 (HTML): Adicione uma única tag de script ao seu arquivo HTML. Esse é o método mais simples, ideal para implementações básicas e protótipos rápidos
• Método 2 (JavaScript dinâmico): Carregar o SDK programaticamente com tratamento de erros e estados de carregamento personalizados. Ideal para aplicativos que precisam de mais controle sobre a integração
• Método 3 (NPM): Use nosso pacote NPM em aplicativos JavaScript modernos. Essa é a nossa abordagem recomendada, com gerenciamento de dependências, agitação de árvore e suporte a TypeScript

1. Adicionar o script do SDK diretamente no HTML

A maneira mais simples de integrar o SDK do Yuno é adicionar um <script> em seu arquivo HTML. Esse método oferece uma implementação rápida e mantém o carregamento assíncrono adequado. O SDK expõe um evento que notifica quando ele está totalmente carregado, garantindo que você possa initialize e usar seus recursos com segurança no momento certo.

📘

Importante

Enquanto o defer garante que o script seja executado depois que o HTML for analisado, mas não garante que o script do SDK sempre será carregado por último. Em alguns casos, se o SDK carregar mais rápido do que o esperado e o ouvinte de eventos for declarado depois, o atributo yuno-sdk-ready pode já ter sido disparado, e seu ouvinte não o detectará. Para evitar isso, sempre defina o ouvinte antes de carregar o script do SDK.

Primeiro, configure o ouvinte de eventos e, em seguida, carregue o SDK:

<script>
  window.addEventListener('yuno-sdk-ready', () => {
    console.log('SDK loaded');
    const yuno = await Yuno.initialize(PUBLIC_API_KEY);
  });
</script>

<script defer src="https://sdk-web.y.uno/v1.5/main.js"></script>

2. Injetar o SDK dinamicamente usando JavaScript

O método de injeção dinâmica de JavaScript oferece controle aprimorado sobre o carregamento e a inicialização do SDK. Essa abordagem permite que você:

• Carregar o SDK programaticamente quando necessário
• Implementar estados de carregamento personalizados e tratamento de erros
• Controle com precisão quando o SDK estiver disponível
• Sincronize a inicialização do SDK com a lógica do seu aplicativo
• Crie um tratamento de erros personalizado para seu caso de uso

Esse método é ideal quando você precisa de controle granular sobre o processo de carregamento do SDK e deseja lidar com vários cenários com precisão.

Crie uma função para injetar o SDK dinamicamente:

export const injectScript = async (): Promise<boolean> => {
  const head = document.getElementsByTagName('head')[0];
  const js = document.createElement('script');
  js.src = "https://sdk-web.y.uno/v1.5/main.js";
  js.defer = true;

  return new Promise((resolve, reject) => {
    window.addEventListener('yuno-sdk-ready', () => {
      resolve(true);
    });

    js.onerror = (error) => {
      const event = new CustomEvent('yuno-sdk-error', { detail: error });
      window.dispatchEvent(event);
      reject(new Error(`Failed to load script: ${js.src} - ${error.message}`));
    };

    head.appendChild(js);
  });
};

Use a função para injetar o SDK:

aguardar injectScript();
const yuno = await YunoinitializePUBLIC_API_KEY);

3. Use o módulo NPM

Para projetos que usam o gerenciamento de pacotes NPM, você pode instalar o SDK como um módulo por meio do NPM. Essa abordagem oferece melhor gerenciamento de dependências, controle de versões e integração perfeita com ferramentas e estruturas modernas de criação de JavaScript. É particularmente vantajoso para aplicativos que usam empacotadores como webpack, Rollup ou Vite.

npm install @yuno-payments/sdk-web

Em seguida, carregue e initialize o SDK da seguinte forma:

import { loadScript } from '@yuno-payments/sdk-web';

const yuno = await loadScript();
const yuno = await Yuno.initialize(PUBLIC_API_KEY);

Melhore o desempenho usando preconnect

Para otimizar o desempenho e reduzir a latência, recomendamos adicionar preconnect o mais cedo possível dentro do <head> de seu documento HTML. Esses links permitem que os navegadores se conectem rapidamente aos nossos servidores antes que os recursos sejam realmente solicitados. Essa abordagem proativa pode melhorar significativamente os tempos de carregamento, especialmente na configuração inicial do SDK e nas chamadas de API subsequentes.

<link rel="preconnect" href="https://sdk-web.y.uno" />
<link rel="preconnect" href="https://api.y.uno" />
<link rel="preconnect" href="https://sdk-web-card.prod.y.uno" />

Implementação Full SDK

Depois de integrar o SDK usando um dos métodos descritos acima, siga estas etapas para implementar a funcionalidade completa de checkout:

Mantenha-se atualizado

Acesse o changelog para obter as atualizações mais recentes do SDK e o histórico de versões.