不太枯燥：如何通过保持应用程序代码简单来展示 SDK

工程师们，想象一下这种情况。您的产品团队同事在星期一早上向您发送了一条 Slack 消息。 “嘿！”她说：“我们刚刚通过采购获得了一个新供应商。”这些话开始在你的胃里打结，就好像你的伴侣刚刚给你发短信说“我们需要谈谈”。

在聊天窗口的底部，Slack 告诉你你的同事正在打字……结收紧了。 “这是一个分析平台，可以让我们更多地了解用户旅程，”她的信息说。 “你认为我们可以在月底之前将它集成到 Web、iOS 和 Android 上吗？”

你知道你的同事只是在做她的工作。毕竟，产品人员确实需要了解用户在新的入职流程中遇到了什么问题，而这个工具应该可以帮助他们。

但是你害怕这对你和你的开发人员意味着什么。上一次您必须实施供应商 SDK 时，就像戴着眼罩从杂乱的房间里寻找出路一样。

一想到必须再次将新 API 背后的心智模型拼凑起来，并将这个系统与你自己的代码库联系起来，而不破坏任何东西，你就会畏缩不前，一直认为我仍然必须构建那个新功能，而且这种集成正在进入我的方式。

这种情况是 mParticle 的工程师非常熟悉的情况。虽然现在我们的开发人员构建而不是实施 SDK，但我们的许多工程师都知道坐在桌子的另一边高唱“新 SDK 蓝调”是什么感觉。

正是这种第一手经验促使我们对 mParticle 开发人员体验进行了最新投资：功能齐全的示例电子商务应用程序网络, iOS ， 和安卓，使用我们的 SDK 实现端到端。

这些应用程序为您提供了一个试验我们的 SDK 和了解事件收集如何与 mParticle 配合使用的场所。它们突出了我们在常见用户操作（如页面查看、产品定制、从购物车中添加/删除按钮和结帐按钮等）上实现的事件的工作示例。

在许多情况下，您可能会发现您可以将这些事件直接复制到您自己的应用程序中，并且只需稍作修改即可满足您特定用例的需求。

在下面的视频中，分别负责 Web 和 iOS 示例应用程序开发的 mParticle 工程师 Alex Sapountzis 和 Peter Jenkins 讨论了他们自己实施供应商 SDK 的经验以及他们开发示例应用程序的原因。

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

“当您实施 mParticle 时，我们希望快速为您提供应用程序和我们系统中发生的情况的思维导图，而无需您进行大量试验和错误，”Matt Bernier 说，开发人员体验高级产品经理mParticle。

“由于这些应用程序向您展示了我们的 SDK 在您正在寻找的环境中运行，因此无需猜测。这意味着您可以完成实施并更快地进入下一个项目。”

深入了解示例应用程序

如果您是 mParticle 客户，您可以查看这些应用程序的运行情况，并在您了解有关我们构建它们的过程的更多信息时直接参考代码。以下是在本地运行应用程序的方法：

注意：您需要访问 mParticle 工作区才能生成 API 密钥。

1. 克隆示例应用程序仓库。
2. 使用npm install 安装包依赖项。
3. 导航到 mParticle 工作区中的设置 > 输入。
4. 选择 Web 平台，然后生成/复制您的 API 密钥。
5. 在此项目的根目录中，将.env.sample重命名为.env。
6. 使用您的 mParticle Web API 密钥更新 REACT_APP_MPARTICLE_API_KEY 环境变量。
7. 使用npm start 运行项目。

目前不是 mParticle 客户？我们的加速器计划是合格的初创公司获得最多一年免费访问 mParticle 的机会。

不太干燥：我们如何通过保持应用程序代码简单来展示我们的 SDK

最重要的是，示例应用程序团队希望这些产品作为工程师学习我们的 SDK 并了解使用 mParticle 实现事件收集的最佳实践的教学工具。

这个目标为示例应用程序背后的许多技术选择提供了依据，从用于构建它们的工具和框架，到整个项目中使用的编码约定。

相关性是 Alex Sapountzis 决定使用 React 作为构建 Web 示例应用程序的框架的主要原因。 React 是最流行的前端框架在世界范围内，用于构建从电子商务网站到流媒体平台的应用程序。

因此可以肯定的是，大多数将要实现 mParticle Web SDK 的 Web 开发人员不必学习 React 就可以从这个示例应用程序中获得价值。

在决定要使用的 React 设计模式时，Alex 试图通过支持相对较新的“内置”功能来取得平衡，例如 React Hooks 和 Context Providers 与 Redux，一个广泛使用的第三方库 -已知的标准架构，但可能会非常复杂和复杂，最终无法为用户提供更清晰的学习体验。

例如，使用自定义挂钩很长一段时间以来，它一直是 React 社区中的一种趋势。使用这些需要创建您自己的函数，这些函数利用常见的 React 钩子来在组件之间共享有状态的逻辑。

Alex 认为在示例应用程序中使用这种方法会妨碍理解我们的 SDK 是如何工作的，因此他选择坚持使用像useEffect 这样的 vanilla hooks。

“如果我把它构建成一个包，有人会在他们的项目中使用，我可能会做一些不同的事情，”亚历克斯说，“但由于这是一个教育工具，我不想让别人担心React 在做什么——我想让他们看看 mParticle 在 React 应用程序中做什么。”

探索 Web 应用程序的组件，您将看到几个示例，其中useEffect用于收集将与 mParticle 事件一起转发的属性，并触发事件本身。这是ProductDetailPage组件上useEffect的一种用法：

 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]);

在这样的实例中使用 vanilla React 钩子可以更容易地理解 mParticle SDK，而不是将此逻辑打包到不同模块中的单独函数中。此外，您可能会注意到这是一个注释较多的代码示例。

示例应用程序开发人员花时间清楚地注释了围绕使用我们的 SDK 的代码——包括事件调用发生的地方，以及支持事件收集的整个逻辑。

这是来自同一组件的另一个示例，展示了注释如何帮助您了解如何在现实生活场景中使用我们的 SDK 的完整上下文，并且无需猜测：

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

Dogfooding 我们自己的 SDK 和功能并利用我们自己的产品

虽然这些示例应用程序的主要目的是帮助我们的客户轻松实施我们的 SDK 并从他们的数据中实现价值，但我们也看到这些应用程序作为一种测试和改进手段的巨大内部价值——或“dogfooding”——我们的自己的 SDK 和面向客户的功能。

在 TypeScript 的荒野中寻找错误

例如，构建 Web 示例应用程序使我们能够发现在将 TypeScript 作为 npm 包的 React 项目中使用我们的核心 Web SDK 时出现的一些边缘情况。

在某些情况下，这三种特定技术之间的相互作用导致了一种竞争条件，在这种情况下，我们的 SDK 在调用事件时并不总是被初始化。

虽然我们的核心 SDK 已经包含处理此问题的逻辑，但 React 包中的某些代码破坏了这些检查并导致发生异常级联。注意到这个问题后，Alex 与 JavaScript API 专家 Rob Ing 进行了一次 bug 搜寻。两人通过堆栈跟踪，修复了问题，并为我们的核心 SDK 发布了补丁。

使用我们自己的数据规划功能

数据收集阶段的不一致是造成数据质量问题进一步的管道。

mParticle 的数据计划工具和功能旨在帮助工程师和其他数据利益相关者协调数据计划、准确实施该计划并实时识别错误。

当我们构建这些示例应用程序时，我们想通过使用我们自己的来实践我们所宣扬的数据规划工具保持事件和属性在这三个平台上的命名、结构和收集方式的一致性。

我们的工程师和 PM 为示例应用程序项目设置了一个专用的 mParticle 工作区，并使用我们的用户界面来创建和生成数据计划。一旦在所有三个应用程序中实现了事件并且我们将事件从 SDK 发送到 mParticle，我们使用 Live Stream 检查收集的数据和预期数据之间的不一致，并使用 Live Stream 的错误消息轻松追踪错误的来源。

使用这些功能可以使创建数据计划、实施事件收集和确保跨平台一致性的过程更加顺畅。我们自己的数据规划功能对创建示例应用程序有很大帮助，我们计划继续使用示例应用程序来测试和改进我们的数据规划功能。

未来该何去何从？

通过使用我们的 SDK 缩短学习曲线、加快实施时间并缩短数据的价值实现时间，这些示例应用程序可以为使用 mParticle 的工程团队带来深远的价值。

我们已经发布了 MLP（“Minimum Loveable Project”，我们的 PM Matt Bernier 创造的一个术语）这一事实标志着我们改进这些资源的工作的开始，而不是结束。

“我认为这绝对是我们将继续投资并随着时间的推移而改进的东西，”Peter Jenkins 说，“从添加额外的评论到始终保持更新我们对 SDK 所做的更改。”

此外，我们还打算继续使用这些应用程序来测试和改进我们的 SDK 和 API 功能，以及我们的整套产品和功能。

例如，在即将推出的网络示例应用程序迭代中，我们计划集成我们的开发人员工具，包括智能型和掉毛.换句话说，正如 Peter Jenkins 所说，这些示例应用程序将成为“关于如何使用我们可以实际运行的 SDK 的常青文档来源。”

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

以前在这里发布。