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.