O que é um SDK? SDK, biblioteca, framework e API

Um SDK (software development kit) empacota uma capacidade junto com tudo o que é preciso para usá-la: uma ou mais APIs, dependências de execução, configuração e credenciais, documentação e exemplos, às vezes uma ferramenta de linha de comando. O que faz de um pacote um SDK não é o volume de código, mas se ele entrega também o trabalho ao redor: autenticação, erros, ferramental. A diferença é concreta. Uma biblioteca resolve "você cansou de escrever essa lógica, use a minha". Um SDK resolve "você precisa integrar esta capacidade externa, e eu já pensei em tudo, da autenticação ao tratamento de falhas".

Separando os quatro termos

Dimensão API Biblioteca Framework SDK
Quem chama quem Você envia requisições Você a chama Ele chama você Você o chama, e ele traz ferramentas
Forma Um contrato de interface (HTTP ou assinatura de função) Código reutilizável Esqueleto, convenções e ciclo de vida Pacote, documentação, configuração e exemplos, talvez uma CLI
Controle Todo seu Todo seu O framework decide o fluxo Seu — um SDK não assume a estrutura da aplicação
Exemplo típico Endpoints REST, GraphQL Datas, gráficos Framework front ou back SDK de nuvem, de pagamento, de feedback
O que ainda cabe a você Tudo Montar e chamar Preencher a lógica dentro das convenções Pedir credenciais, inicializar conforme a documentação
Regra de bolso: API é contrato, biblioteca é peça, framework é esqueleto, e SDK é a peça mais o manual mais o diagrama de ligação.

O que costuma haver dentro de um SDK

Componente Função O que quebra sem ele
Camada sobre a API Transforma detalhes HTTP, retentativas e códigos de erro em funções Cada integrador reescreve, com comportamento diferente
Runtime e dependências Faz rodar no ambiente alvo (navegador, servidor Node) Conflito de versões, tamanho de bundle fora de controle
Configuração e credenciais Chaves, região, ambiente, chaves de liga/desliga Segredos no código, teste e produção misturados
Documentação e exemplos Leva alguém à primeira chamada em dez minutos A integração depende de perguntar a uma pessoa, e o suporte cai em você
Ferramental (opcional) CLI, painel de depuração, definições de tipo Diagnosticar vira adivinhação
A última linha costuma ser tratada como bônus. Na prática, decide a reputação do SDK: SDKs com tipos completos e ferramentas de depuração geram bem menos retrabalho para quem integra.

Três formas de distribuir, três perfis de custo

Forma Como a versão é fixada Quem atualiza Custo principal
Gerenciador de pacotes (npm e similares) O lockfile fixa uma versão O integrador, de propósito Exige pipeline de build; versões antigas vivem anos
Tag script (CDN) Definida pela URL ou pela configuração O fornecedor A CSP precisa liberar o domínio; o cache precisa ser pensado
Embutido numa plataforma Segue a versão da plataforma A plataforma Você quase não controla o ritmo
A tag script serve para tudo o que "os visitantes também precisam usar": sem instalação, sem build, uma linha e funciona. O preço é que compatibilidade de versões e lista branca de CSP ficam com você. É por isso que muitos SDKs de feedback e suporte escolhem esse caminho.

O custo escondido de um SDK próprio

Empacotar uma funcionalidade como SDK é fácil. Conviver com ela por cinco anos não:
  • Compatibilidade retroativa: nomes de funções, parâmetros e momentos de callback não mudam livremente depois de publicados. Uma mudança e todos os integradores precisam acompanhar.
  • Tamanho e desempenho: o SDK roda na página de outra pessoa. 100 KB a mais podem mexer nas métricas de primeira renderização.
  • Privacidade e conformidade: o que é coletado, por quanto tempo e se pode ser desligado precisa estar escrito e ser verdade — nossos limites estão na política de privacidade.
  • Observabilidade: quando o SDK quebra, o integrador só diz "a sua coisa quebrou". Você precisa do seu próprio relato de erros e da distribuição de versões.
  • Documentação e exemplos: um SDK sem documentação não é um SDK; o custo volta como ticket de suporte.
  • Desses cinco, os três primeiros são os clássicos "invisíveis antes do lançamento, inevitáveis depois".

    Como é um SDK de feedback

    O SDK web do BugCapturer pede dois passos: criar um projeto e definir uma lista branca de domínios no console, e então colocar o script na página.
    html
    <script>window.BugCapturerConfig={key:"bcpk_xxxxxxxx",position:"bottom-right",requireContact:false}</script>
    <script src="https://api.bugcapturer.com/sdk/bugcapturer.js" async></script>
    
    A superfície de configuração é pequena, e cada opção tem um limite claro:
    Opção Função Atenção
    key Identificador do projeto Público por design; o acesso é limitado pela lista branca de domínios
    position Posição do botão flutuante Não cobrir botões de checkout ou de suporte
    requireContact Se o visitante precisa deixar contato Desligue em sites públicos, senão a taxa de envio cai
    reporter Identidade de quem relata, passada pelo site Nunca fixe uma única pessoa; preencha a partir da sessão
    A experiência do visitante merece ser dita com precisão: quem tem a extensão delega a captura a ela, sem nenhum diálogo de permissão; quem não tem vê um pedido de permissão do navegador por relato e então a captura é feita. É o modelo de segurança do navegador, não preguiça — qualquer SDK web que prometa "capturas totalmente invisíveis" merece uma pergunta sobre como faz isso. A instalação completa está no início rápido do SDK web; este artigo não repete.

    Um SDK não é uma extensão de navegador

    Os dois são chamados de "formas de integrar", mas as fronteiras diferem:
    Dimensão SDK Extensão de navegador
    Quem instala O site, no código Cada pessoa, individualmente
    Quem é alcançado Todos os visitantes Só quem instalou
    Origem da permissão Lista branca de domínios mais consentimento por relato Permissões declaradas pela extensão
    Encaixa em Coletar feedback de clientes Testes e revisões internas
    Limite principal Exige mudança de código no site Clientes não instalam extensão por um site
    Então "deixar o cliente relatar" é, no fundo, um problema de SDK ou de link compartilhado; a extensão é para uso interno. A comparação está em Extensão do Chrome vs ferramentas desktop.

    Lendo os números de versão

    Versionamento importa mais do que numa biblioteca comum, porque quem atualiza não é você:
    • Maior: mudanças incompatíveis; o integrador precisa alterar código.
    • Menor: funções novas, compatíveis; em geral seguro.
    • Correção: ajustes de bug; risco mais baixo.
    Na tag script, a versão mora na URL. O fornecedor deveria oferecer dois modos: fixado (o integrador decide quando migrar) e automático (sempre a última). Fixado é estável; automático é prático, mas só se você confia que uma atualização não vai quebrar a página de ninguém — exatamente onde nascem muitos incidentes de SDK.

    Cinco perguntas antes de integrar um SDK

    Pergunta Por que importa Como é uma boa resposta
    Que permissões ele pede? Scripts e extensões podem ler o conteúdo da página Escopo mínimo, cada item explicado, pode ser desligado
    Que dados ele coleta? Conformidade e confiança do cliente Lista clara, campos sensíveis mascarados, prazo de retenção
    Uma falha derruba a página? Erros de scripts de terceiros se propagam Timeouts não bloqueiam o fluxo principal, erros isolados
    Tamanho e momento de carga? Impacto direto na primeira renderização Carga assíncrona, inicialização sob demanda, tamanho publicado
    Como saímos? O custo de migração é subestimado Exportar dados, remover em uma linha, sem resíduos
    As perguntas dois e cinco são as mais puladas, e as que viram problema seis meses depois.

    Construir ou comprar

    Sua situação Recomendação
    A capacidade é o seu negócio central (você é o serviço de pagamento) Construir; o SDK é o produto
    Você só precisa de um ponto de entrada e não tem quem mantenha Comprar ou adotar, e investir o tempo de engenharia no negócio
    A conformidade exige que os dados fiquem na sua rede Construir ou auto-hospedar, depois de calcular a manutenção
    Menos de cinco engenheiros e sem infraestrutura front Começar com tag script; não construir seu próprio empacotamento
    O único critério que importa: essa capacidade vai continuar comendo o seu roadmap? Se sim, construa. Se não, não assuma um passivo de longo prazo só para sentir controle.

    Três equívocos comuns

    • Chamar uma API de SDK: documentação de endpoints sem camada, exemplos e configuração continua sendo API.
    • Tratar SDK como framework: um SDK não deve assumir a estrutura da aplicação. Se ele dita a sua árvore de pastas, é framework.
    • Quanto mais completo, melhor: um SDK que faz tudo costuma significar bundle grande, permissões amplas e atualizações arriscadas. Importe o que você usa.

    FAQ

    Qual é a relação entre SDK e API? Um SDK normalmente contém uma camada sobre uma API. A API é o contrato; o SDK é a implementação dele com ferramentas e documentação. SDK versus biblioteca em uma frase? Biblioteca é código que você chama. SDK é tudo o que você precisa para integrar uma capacidade — biblioteca, configuração, documentação e ferramentas incluídas. Uma tag script de front-end é um SDK? Sim. A distribuição não decide se é SDK; decide apenas como versões e responsabilidade de atualização são divididas. Um SDK afeta o desempenho da página? Sim, conforme tamanho e momento de carga. Carregar de forma assíncrona e inicializar sob demanda é o padrão; o fornecedor deveria publicar o tamanho. Preciso mudar a configuração de build? Com tag script, não — é por isso que serve a sites públicos. Com gerenciador de pacotes, sim, em troca de versão fixa e tipos.