Não muito seco: como mostrar SDKs mantendo o código do aplicativo simples

Engenheiros, imaginem este cenário. Seu colega da equipe de produto envia uma mensagem do Slack para você na segunda-feira de manhã. "Ei!" Ela diz: “Acabamos de receber um novo fornecedor por meio de compras”. As palavras começam a dar um nó em seu estômago, como se seu parceiro tivesse acabado de enviar uma mensagem para você dizendo “precisamos conversar”.

Na parte inferior da janela de bate-papo, o Slack informa que seu colega está digitando... . e o nó aperta. “É uma plataforma de análise que nos dará mais visibilidade sobre as jornadas do usuário”, diz sua mensagem. “Você acha que podemos integrá-lo na Web, iOS e Android até o final do mês?”

Você sabe que sua colega está apenas fazendo o trabalho dela. Afinal, o pessoal do produto precisa ver onde os usuários estão travando no novo fluxo de integração, e essa ferramenta deve ajudá-los.

Mas você teme o que isso significa para você e seus colegas desenvolvedores. A última vez que você teve que implementar um SDK de fornecedor, foi como sair de uma sala desordenada enquanto usava uma venda nos olhos.

Você se encolhe ao pensar mais uma vez em ter que juntar o modelo mental por trás de uma nova API e vincular esse sistema à sua própria base de código sem quebrar nada, o tempo todo pensando que ainda tenho que construir esse novo recurso, e essa integração está chegando o meu caminho.

Esta situação é uma situação com a qual os engenheiros da mParticle estão intimamente familiarizados. Embora hoje em dia nossos desenvolvedores criem SDKs em vez de implementá-los, muitos de nossos engenheiros sabem como é estar do outro lado da mesa cantando o “New SDK Blues”.

É essa experiência em primeira mão que nos levou a fazer nosso mais recente investimento na experiência do desenvolvedor mParticle: aplicativos de comércio eletrônico de amostra totalmente funcionais para Rede , iOS , e Android , implementado de ponta a ponta com nossos SDKs.

Esses aplicativos fornecem a você um playground para experimentar nosso SDK e aprender como a coleta de eventos funciona com o mParticle. Eles destacam exemplos funcionais de nossos eventos implementados em ações comuns do usuário, como exibições de página, personalizações de produtos, botões de adicionar/remover do carrinho e botões de checkout, entre outros.

Em muitos casos, você pode descobrir que é capaz de copiar esses eventos diretamente em seu próprio aplicativo e fazer apenas pequenas modificações para atender às necessidades de seu caso de uso específico.

No vídeo abaixo, Alex Sapountzis e Peter Jenkins, os engenheiros da mParticle que lideraram o desenvolvimento de aplicativos de amostra para Web e iOS, respectivamente, discutem suas próprias experiências na implementação de SDKs de fornecedores e por que desenvolveram os aplicativos de amostra.

https://www.youtube.com/watch?v=1hYc9qalrXQ

“Queremos fornecer rapidamente um mapa mental do que acontece em seu aplicativo e em nosso sistema quando você implementa o mParticle, sem exigir que você passe por muitas tentativas e erros”, diz Matt Bernier, gerente de produto sênior de experiência do desenvolvedor na mParticle.

“Como esses aplicativos mostram nossos SDKs em execução exatamente no contexto que você está procurando, não há adivinhação. Isso significa que você pode concluir sua implementação e passar para o próximo projeto mais rapidamente.”

Olhando sob o capô dos aplicativos de exemplo

Se você é um cliente do mParticle, pode ver esses aplicativos em ação e consultar o código diretamente à medida que aprende mais sobre nosso processo de criá-los. Veja como você pode executar o aplicativo localmente:

Observação: você precisará acessar um espaço de trabalho mParticle para gerar uma chave de API.

1. clonar o repositório de aplicativos de amostra .
2. Instale as dependências do pacote usando npm install.
3. Navegue até Configuração > Entradas em seu espaço de trabalho mParticle.
4. Selecione a plataforma da Web e gere/copie sua chave de API.
5. Na raiz deste projeto, renomeie .env.sample para .env.
6. Atualize a variável de ambiente REACT_APP_MPARTICLE_API_KEY com sua chave de API da Web mParticle.
7. Execute o projeto usando npm start.

Atualmente não é um cliente mParticle? Nosso Programa Acelerador é uma oportunidade para startups qualificadas receberem até um ano de acesso gratuito ao mParticle.

Não muito seco: como apresentamos nosso SDK mantendo o código do aplicativo simples

Acima de tudo, a equipe de aplicativos de amostra queria que esses produtos servissem como ferramentas de ensino para os engenheiros aprenderem nossos SDKs e entenderem as práticas recomendadas para implementar a coleta de eventos com mParticle.

Esse objetivo informou muitas das escolhas técnicas por trás dos aplicativos de amostra, desde as ferramentas e estruturas usadas para criá-los até as convenções de codificação usadas nos projetos.

A capacidade de relacionamento foi a principal razão pela qual Alex Sapountzis decidiu usar o React como a estrutura para criar o aplicativo de exemplo da web. Reagir é o framework de front-end mais popular no mundo e é usado para criar aplicativos que vão desde sites de comércio eletrônico até plataformas de streaming.

Portanto, é uma aposta segura que a maioria dos desenvolvedores da Web que implementariam o mParticle Web SDK não precisaria aprender React antes de poder obter valor desse aplicativo de amostra.

Quando se tratava de decidir sobre os padrões de design do React a serem usados, Alex tentou encontrar um equilíbrio favorecendo recursos relativamente novos 'incorporados', como React Hooks e Context Providers versus Redux, uma biblioteca de terceiros que é amplamente utilizada. arquitetura padrão conhecida, mas pode ser muito opressiva e complexa para oferecer uma experiência de aprendizado mais clara ao usuário.

Por exemplo, usando ganchos personalizados tem sido uma tendência dentro da comunidade React por algum tempo. O uso deles envolve a criação de suas próprias funções que aproveitam os ganchos comuns do React com o objetivo de compartilhar a lógica de estado entre os componentes.

Alex sentiu que usar essa abordagem nos aplicativos de amostra atrapalharia a compreensão de como nosso SDK está funcionando e, por esse motivo, ele optou por continuar usando ganchos básicos como useEffect.

“Se eu estivesse construindo isso como um pacote que alguém usaria em seu projeto, talvez eu tivesse feito as coisas de maneira um pouco diferente”, diz Alex, “mas como se trata de uma ferramenta educacional, não queria que alguém tivesse que se preocupar com o que o React está fazendo – eu queria que eles vissem o que o mParticle está fazendo em um aplicativo React.”

Explorando os componentes do aplicativo da Web, você verá vários exemplos nos quais useEffect é usado para coletar os atributos que serão encaminhados com eventos mParticle e disparar os próprios eventos. Aqui está um desses usos de useEffect no componente ProductDetailPage :

 useEffect(() => { // Generates a Product View Detail Event to signal that a customer // viewed the product details, potentially leading to an 'Add to Cart' Event if (product) { // Generate an mParticle Product Object before sending any eCommerce Events const mParticleProduct: mParticle.Product = getMPProduct(product); // Fire a single eCommerce Product View Detail Event for this product page mParticle.eCommerce.logProductAction( mParticle.ProductActionType.ViewDetail, mParticleProduct, ); } // If you re-render and the product changes, // this will re-fire a new Product View Detail Event }, [product]);

Usar o hook vanilla React em instâncias como essa torna muito mais fácil entender o mParticle SDK do que se essa lógica fosse empacotada em funções separadas em diferentes módulos. Além disso, você pode perceber que este é um exemplo de código bastante cheio de comentários.

Os desenvolvedores de aplicativos de amostra reservaram um tempo para comentar claramente o código que envolve o uso de nosso SDK – tanto onde as chamadas de evento ocorrem quanto em toda a lógica que oferece suporte à coleta de eventos.

Aqui está outro exemplo do mesmo componente mostrando como os comentários ajudam a fornecer o contexto completo de como usar nosso SDK em cenários da vida real e não deixam nada para adivinhação:

 // It is recommended to use mParticle.createProduct when using our // eCommerce logging functions to generate events so that you can // be sure to include all of our data points properly const getMPProduct = (_product: Product): mParticle.Product => { const { label, id, price } = _product; // When passing attributes into mParticle, it's best to not include // undefined or null values const attributes: mParticle.SDKEventAttrs = {}; if (color) { attributes.color = color; } if (size) { attributes.size = size; } // In this example we are not fulling handling multiple brands, // categories and other use cases for a fully fledged e-Commerce // application. As such, we are passing undefined for many of these // attributes to highlight cases where you want may need some // parameters but not all of them. return mParticle.eCommerce.createProduct( label, id, price, parseInt(quantity, 10), undefined, // Variant: used for single variants. // Use Custom ATtributes for multiple variants like // in this use case undefined, // Category undefined, // Brand undefined, // Position undefined, // Coupon Code attributes, ); };

https://www.youtube.com/watch?v=6zbW4X8Oyg0

Fazendo dogfood com nossos próprios SDKs e recursos e aproveitando nossos próprios produtos

Embora o objetivo principal desses aplicativos de amostra seja ajudar nossos clientes a implementar facilmente nosso SDK e obter valor de seus dados, também vimos um grande valor interno desses aplicativos como um meio de testar e melhorar––ou “dogfooding”––nosso próprios SDKs e recursos voltados para o cliente.

Caça aos Bugs na Selva do TypeScript

Por exemplo, construir o aplicativo de amostra da web nos permitiu descobrir alguns casos extremos que surgem ao usar nosso SDK da web principal em um projeto React com TypeScript como um pacote npm.

Em alguns casos, a interação entre essas três tecnologias específicas resultou em uma condição de corrida na qual nosso SDK nem sempre seria inicializado quando um evento fosse chamado.

Embora nosso SDK principal já contivesse lógica para lidar com isso, certos códigos nos pacotes do React quebraram essas verificações e causaram uma cascata incomum. Depois de perceber esse problema, Alex saiu em busca de bugs com o colega guru da API JavaScript Rob Ing. Os dois vasculharam o rastreamento de pilha, corrigiram o problema e lançaram patches para nosso SDK principal.

Usando nossos próprios recursos de planejamento de dados

Inconsistências na fase de coleta de dados são uma das maiores causas de problemas de qualidade de dados mais abaixo na tubulação.

As ferramentas e recursos de planejamento de dados do mParticle são projetados para ajudar engenheiros e outras partes interessadas em dados a se alinharem em um plano de dados, implementar esse plano com precisão e identificar erros em tempo real.

Quando criamos esses aplicativos de amostra, queríamos praticar o que pregamos usando nossos próprios ferramentas de planejamento de dados para manter a consistência com a forma como os eventos e atributos são nomeados, estruturados e coletados nessas três plataformas.

Nossos engenheiros e PMs configuraram um espaço de trabalho mParticle dedicado para o projeto de aplicativos de exemplo e usaram nossa interface de usuário para criar e gerar planos de dados. Depois que os eventos foram implementados em todos os três aplicativos e estávamos enviando eventos dos SDKs para o mParticle, usamos o Live Stream para verificar desalinhamentos entre os dados coletados e esperados e as mensagens de erro do Live Stream para rastrear facilmente a origem dos erros.

O uso desses recursos tornou o processo de criação de planos de dados, implementação de coleta de eventos e garantia de consistência entre plataformas muito mais suave. Nossos próprios recursos de planejamento de dados foram uma ajuda significativa na criação dos aplicativos de exemplo e planejamos continuar usando os aplicativos de exemplo para testar e melhorar nossos recursos de planejamento de dados.

O que o futuro guarda?

Reduzindo a curva de aprendizado com nosso SDK, acelerando o tempo de implementação e diminuindo o tempo de valorização de seus dados, esses aplicativos de amostra podem agregar valor de longo alcance às equipes de engenharia que trabalham com o mParticle.

O fato de termos enviado nosso MLP (“Minimum Loveable Project”, um termo que nosso PM Matt Bernier cunhou) marca o início, não o fim, de nosso trabalho para melhorar esses recursos.

“Acho que isso é definitivamente algo em que continuaremos investindo e melhorando com o tempo”, diz Peter Jenkins, “desde adicionar comentários adicionais até sempre mantê-lo atualizado com as alterações que fazemos no SDK”.

Além disso, também pretendemos continuar usando esses aplicativos como meio de testar e melhorar não apenas nossos recursos de SDK e API, mas também todo o nosso conjunto de produtos e recursos.

Nas próximas iterações do aplicativo de amostra da Web, por exemplo, planejamos integrar nossas ferramentas de desenvolvedor, incluindo Smarttype e Linting . Em outras palavras, esses aplicativos de amostra serão, como diz Peter Jenkins, “uma fonte perene de documentação para saber exatamente como usar nosso SDK que você pode realmente executar”.

https://www.youtube.com/watch?v=Z02F77Yfs_E

Anteriormente publicado aqui.