Pas trop sec : comment présenter les SDK en gardant le code d'application simple

Ingénieurs, imaginez ce scénario. Votre collègue de l'équipe produit vous envoie un message Slack un lundi matin. "Hé!" Elle dit : « Nous venons d'avoir un nouveau fournisseur grâce à l'approvisionnement. Les mots commencent à faire un nœud dans votre estomac, comme si votre partenaire venait de vous envoyer un texto en disant « nous devons parler ».

Au bas de la fenêtre de discussion, Slack vous indique que votre collègue est en train de taper... . et le noeud se resserre. "C'est une plate-forme d'analyse qui nous donnera plus de visibilité sur les parcours des utilisateurs", indique son message. "Pensez-vous que nous pourrons l'intégrer sur le Web, iOS et Android d'ici la fin du mois ?"

Vous savez que votre collègue ne fait que son travail. Après tout, les gens du produit ont besoin de voir où les utilisateurs sont bloqués dans le nouveau flux d'intégration, et cet outil devrait les aider.

Mais vous redoutez ce que cela signifie pour vous et vos collègues développeurs. La dernière fois que vous avez dû implémenter un SDK fournisseur, c'était comme sortir d'une pièce encombrée tout en portant un bandeau sur les yeux.

Vous grincer des dents à l'idée de devoir une fois de plus reconstituer le modèle mental derrière une nouvelle API et lier ce système à votre propre base de code sans rien casser, tout en pensant que je dois encore créer cette nouvelle fonctionnalité, et cette intégration est en train d'entrer mon chemin.

Cette situation est une situation avec laquelle les ingénieurs de mParticle sont intimement familiers. Alors qu'aujourd'hui nos développeurs construisent plutôt qu'implémentent des SDK, beaucoup de nos ingénieurs savent ce que c'est que d'être de l'autre côté de la table en train de chanter le « New SDK Blues ».

C'est cette expérience de première main qui nous a poussés à faire notre dernier investissement dans l'expérience de développement de mParticle : des exemples d'applications de commerce électronique entièrement fonctionnelles pour la toile , iOS , et Android , mis en œuvre de bout en bout avec nos SDK.

Ces applications vous offrent un terrain de jeu pour expérimenter notre SDK et apprendre comment la collecte d'événements fonctionne avec mParticle. Ils mettent en évidence des exemples concrets de nos événements mis en œuvre sur des actions utilisateur courantes telles que les pages vues, les personnalisations de produits, les boutons d'ajout/de suppression du panier et les boutons de paiement, entre autres.

Dans de nombreux cas, vous constaterez que vous pouvez copier ces événements directement dans votre propre application et n'apporter que de légères modifications pour répondre aux besoins de votre cas d'utilisation spécifique.

Dans la vidéo ci-dessous, Alex Sapountzis et Peter Jenkins, les ingénieurs de mParticle qui ont respectivement dirigé le développement des exemples d'applications Web et iOS, discutent de leurs propres expériences de mise en œuvre des SDK des fournisseurs et expliquent pourquoi ils ont développé les exemples d'applications.

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

"Nous voulons vous donner rapidement une carte mentale de ce qui se passe à la fois dans votre application et dans notre système lorsque vous implémentez mParticle, sans vous obliger à passer par beaucoup d'essais et d'erreurs", déclare Matt Bernier, responsable produit senior de l'expérience développeur chez mParticule.

« Étant donné que ces applications vous montrent nos SDK fonctionnant exactement dans le contexte que vous recherchez, il n'y a pas de conjecture. Cela signifie que vous pouvez terminer votre mise en œuvre et passer au projet suivant plus rapidement.

Regarder sous le capot des exemples d'applications

Si vous êtes un client mParticle, vous pouvez voir ces applications en action et vous référer directement au code au fur et à mesure que vous en apprenez plus sur notre processus de création. Voici comment exécuter l'application localement :

Remarque : vous aurez besoin d'accéder à un espace de travail mParticle pour générer une clé API.

1. Cloner le exemple de référentiel d'applications .
2. Installez les dépendances du package à l'aide de npm install.
3. Accédez à Configuration > Entrées dans votre espace de travail mParticle.
4. Sélectionnez la plateforme Web et générez/copiez votre clé API.
5. À la racine de ce projet, renommez .env.sample en .env.
6. Mettez à jour la variable d'environnement REACT_APP_MPARTICLE_API_KEY avec votre clé API Web mParticle.
7. Exécutez le projet à l'aide de npm start.

Vous n'êtes pas actuellement client de mParticle ? Notre Programme d'accélération est une opportunité pour les startups qualifiées de recevoir jusqu'à un an d'accès gratuit à mParticle.

Pas trop sec : comment nous avons présenté notre SDK en gardant le code d'application simple

Par-dessus tout, l'équipe des exemples d'applications souhaitait que ces produits servent d'outils pédagogiques permettant aux ingénieurs d'apprendre nos SDK et de comprendre les meilleures pratiques pour la mise en œuvre de la collecte d'événements avec mParticle.

Cet objectif a éclairé de nombreux choix techniques derrière les exemples d'applications, des outils et cadres utilisés pour les créer, aux conventions de codage utilisées tout au long des projets.

La relatabilité était la principale raison pour laquelle Alex Sapountzis a décidé d'utiliser React comme cadre dans lequel créer l'exemple d'application Web. Réagir est le framework frontal le plus populaire dans le monde et est utilisé pour créer des applications allant des sites de commerce électronique aux plateformes de streaming.

Il y a donc fort à parier que la plupart des développeurs Web qui implémenteraient le mParticle Web SDK n'auraient pas à apprendre React avant de pouvoir tirer parti de cet exemple d'application.

Lorsqu'il s'agissait de décider des modèles de conception React à utiliser, Alex a essayé de trouver un équilibre en favorisant des fonctionnalités « intégrées » relativement nouvelles, telles que React Hooks et Context Providers par rapport à Redux, une bibliothèque tierce largement utilisée. architecture standard connue, mais peut être très écrasante et complexe pour finalement offrir une expérience d'apprentissage plus claire à l'utilisateur.

Par exemple, en utilisant crochets personnalisés est une tendance au sein de la communauté React depuis un certain temps. Leur utilisation implique la création de vos propres fonctions qui exploitent les crochets React communs dans le but de partager la logique avec état entre les composants.

Alex a estimé que l'utilisation de cette approche dans les exemples d'applications aurait empêché de comprendre le fonctionnement de notre SDK, et pour cette raison, il a choisi de s'en tenir à l'utilisation de crochets vanille comme useEffect.

"Si je construisais cela comme un package que quelqu'un utiliserait dans son projet, j'aurais peut-être fait les choses un peu différemment", dit Alex, "mais étant donné qu'il s'agit d'un outil pédagogique, je ne voulais pas que quelqu'un ait à s'inquiéter de ce que fait React––Je voulais qu'ils voient ce que mParticle fait dans une application React.

En explorant les composants de l'application Web, vous verrez plusieurs exemples dans lesquels useEffect est utilisé à la fois pour collecter les attributs qui seront transmis avec les événements mParticle et déclencher les événements eux-mêmes. Voici une telle utilisation de useEffect sur le composant 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]);

L'utilisation du hook vanilla React dans des cas comme celui-ci facilite la compréhension du SDK mParticle que si cette logique était regroupée dans des fonctions distinctes dans différents modules. En outre, vous remarquerez peut-être qu'il s'agit d'un exemple de code plutôt riche en commentaires.

Les développeurs de l'exemple d'application ont pris le temps de commenter clairement le code entourant l'utilisation de notre SDK, à la fois là où les appels d'événements ont lieu et dans la logique qui prend en charge la collecte d'événements.

Voici un autre exemple du même composant montrant comment les commentaires aident à vous donner le contexte complet de la façon d'utiliser notre SDK dans des scénarios réels, et ne laissez rien à deviner :

 // 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

Dogfooder nos propres SDK et fonctionnalités et tirer parti de nos propres produits

Bien que l'objectif principal de ces exemples d'applications soit d'aider nos clients à mettre en œuvre facilement notre SDK et à tirer parti de leurs données, nous avons également constaté une grande valeur interne de ces applications en tant que moyen de tester et d'améliorer - ou de "dogfooding" - notre propres SDK et fonctionnalités orientées client.

Chasse aux bogues dans la nature sauvage de TypeScript

Par exemple, la création de l'exemple d'application Web nous a permis de découvrir certains cas extrêmes qui surviennent lors de l'utilisation de notre SDK Web principal dans un projet React avec TypeScript en tant que package npm.

Dans certains cas, l'interaction entre ces trois technologies particulières a entraîné une condition de concurrence dans laquelle notre SDK n'était pas toujours initialisé lorsqu'un événement était appelé.

Alors que notre SDK principal contenait déjà une logique pour gérer cela, certains codes dans les packages de React ont enfreint ces vérifications et provoqué une cascade inhabituelle. Après avoir remarqué ce problème, Alex s'est lancé dans une chasse aux bogues avec son collègue gourou de l'API JavaScript, Rob Ing. Les deux ont parcouru la trace de la pile, résolu le problème et publié des correctifs pour notre SDK principal.

Utilisation de nos propres fonctionnalités de planification des données

Les incohérences au stade de la collecte des données sont l'une des principales causes de problèmes de qualité des données plus loin dans le pipeline.

Les outils et fonctionnalités de planification des données de mParticle sont conçus pour aider les ingénieurs et les autres parties prenantes des données à s'aligner sur un plan de données, à mettre en œuvre ce plan avec précision et à identifier les erreurs en temps réel.

Lorsque nous avons créé ces exemples d'applications, nous voulions mettre en pratique ce que nous prêchons en utilisant nos propres outils de planification des données pour maintenir la cohérence avec la façon dont les événements et les attributs sont nommés, structurés et collectés sur ces trois plates-formes.

Nos ingénieurs et PM ont mis en place un espace de travail mParticle dédié pour le projet d'exemples d'applications et ont utilisé notre interface utilisateur pour créer et générer des plans de données. Une fois que les événements ont été implémentés dans les trois applications et que nous envoyions des événements des SDK à mParticle, nous avons utilisé Live Stream pour vérifier les désalignements entre les données collectées et attendues, et la messagerie d'erreur de Live Stream pour retrouver facilement la source des erreurs.

L'utilisation de ces fonctionnalités a rendu le processus de création de plans de données, de mise en œuvre de la collecte d'événements et d'assurance de la cohérence entre plates-formes beaucoup plus fluide. Nos propres fonctionnalités de planification des données ont été d'une aide significative dans la création des exemples d'applications, et nous prévoyons de continuer à utiliser les exemples d'applications pour tester et améliorer nos fonctionnalités de planification des données.

Que réserve l'avenir?

En réduisant la courbe d'apprentissage avec notre SDK, en accélérant le temps de mise en œuvre et en réduisant le délai de valorisation de vos données, ces exemples d'applications peuvent apporter une valeur considérable aux équipes d'ingénierie travaillant avec mParticle.

Le fait que nous ayons livré notre MLP ("Minimum Loveable Project", un terme que notre PM Matt Bernier a inventé) marque le début, et non la fin, de notre travail sur l'amélioration de ces ressources.

"Je pense que c'est certainement quelque chose dans lequel nous allons continuer à investir et à améliorer au fil du temps", déclare Peter Jenkins, "de l'ajout de commentaires supplémentaires à la mise à jour permanente des modifications que nous apportons au SDK."

De plus, nous avons également l'intention de continuer à utiliser ces applications comme moyen de tester et d'améliorer non seulement nos fonctionnalités SDK et API, mais aussi toute notre suite de produits et de fonctionnalités.

Dans les prochaines itérations de l'exemple d'application Web, par exemple, nous prévoyons d'intégrer nos outils de développement, notamment Type intelligent et peluchage . En d'autres termes, ces exemples d'applications seront, comme le dit Peter Jenkins, "une source de documentation toujours à jour pour savoir exactement comment utiliser notre SDK que vous pouvez réellement exécuter".

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

Précédemment publié ici.