Не слишком сухо: как продемонстрировать SDK, сохранив код приложения простым

Инженеры, представьте себе этот сценарий. Ваш коллега по продукту отправляет вам сообщение в Slack в понедельник утром. "Привет!" Она говорит: «Мы только что получили нового поставщика через отдел закупок». Слова начинают завязывать узел в вашем животе, как будто ваш партнер только что написал вам сообщение о том, что «нам нужно поговорить».

В нижней части окна чата Slack сообщает, что ваш коллега вводит.... и узел затягивается. «Это аналитическая платформа, которая даст нам больше информации о пути пользователя», — говорится в ее сообщении. «Как вы думаете, сможем ли мы интегрировать его в веб, iOS и Android к концу месяца?»

Вы знаете, что ваша коллега просто делает свою работу. В конце концов, разработчики продукта должны видеть, где пользователи застревают в новом потоке адаптации, и этот инструмент должен им помочь.

Но вы боитесь, что это значит для вас и ваших коллег-разработчиков. В последний раз, когда вам приходилось внедрять SDK поставщика, это было похоже на поиск выхода из захламленной комнаты с завязанными глазами.

Вы содрогаетесь при мысли о том, что вам снова придется собрать воедино ментальную модель нового API и связать эту систему с вашей собственной кодовой базой, ничего не нарушая, при этом думая * Мне все еще нужно создать эту новую функцию, и эта интеграция становится все более по моему.*

Эта ситуация хорошо знакома инженерам mParticle. Хотя в наши дни наши разработчики создают, а не внедряют SDK, многие из наших инженеров знают, каково это быть по другую сторону стола и петь «New SDK Blues».

Именно этот непосредственный опыт побудил нас сделать наши последние инвестиции в опыт разработчиков mParticle: полнофункциональные образцы приложений электронной коммерции для Web. , iOS и  Android, полностью реализованный с наши SDK.

Эти приложения предоставляют вам площадку для экспериментов с нашим SDK и изучения того, как сбор событий работает с mParticle. Они освещают рабочие примеры наших событий, реализованных для обычных действий пользователя, таких как просмотры страниц, настройки продуктов, кнопки добавления/удаления из корзины и кнопки оформления заказа, среди прочего.

Во многих случаях вы можете обнаружить, что можете копировать эти события непосредственно в свое собственное приложение и вносить лишь небольшие изменения для удовлетворения потребностей вашего конкретного варианта использования.

В видео ниже Алекс Сапунцис и Питер Дженкинс, инженеры mParticle, которые руководили разработкой примеров приложений для Интернета и iOS соответственно, рассказывают о своем собственном опыте внедрения SDK поставщиков и о том, почему они разработали примеры приложений.

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

«Мы хотим быстро дать вам ментальную карту того, что происходит как в вашем приложении, так и в нашей системе, когда вы внедряете mParticle, не требуя от вас множества проб и ошибок», — говорит Мэтт Бернье, старший менеджер по продуктам для разработчиков в mParticle.

«Поскольку эти приложения показывают вам, как наши SDK работают именно в том контексте, который вы ищете, нет никаких догадок. Это означает, что вы можете завершить внедрение и быстрее перейти к следующему проекту».

Заглянем внутрь примеров приложений

Если вы являетесь клиентом mParticle, вы можете увидеть эти приложения в действии и напрямую обратиться к коду, когда узнаете больше о нашем процессе их создания. Вот как вы можете запустить приложение локально:

Примечание: вам потребуется доступ к рабочей области mParticle для создания ключа API.

1. Клонируйте репозиторий примеров приложений.

1. Установите зависимости пакета, используя npm install.

1. Перейдите в «Настройка» > «Входные данные» в рабочей области mParticle.

1. Выберите веб-платформу и сгенерируйте/скопируйте свой ключ API.

1. В корне проекта переименуйте .env.sample в .env..

1. Обновите переменную среды REACT_APP_MPARTICLE_API_KEY, указав свой ключ веб-API mParticle.

1. Запустите проект, используя npm start.

В настоящее время не являетесь клиентом mParticle? Наша Программа акселерации – это возможность для квалифицированных стартапов получить до одного года бесплатного доступа к mParticle.

Не слишком СУХО: как мы продемонстрировали наш SDK, сохранив код приложения простым

Помимо всего прочего, команда разработчиков примеров приложений хотела, чтобы эти продукты служили обучающими инструментами для инженеров, которые могли бы изучить наши SDK и понять лучшие практики реализации сбора событий с помощью mParticle.

Эта цель информировала о многих технических решениях, стоящих за примерами приложений, от инструментов и сред, используемых для их создания, до соглашений о кодировании, используемых во всех проектах.

Релятивность была основной причиной, по которой Алекс Сапунцис решил использовать React в качестве основы для создания примера веб-приложения. React — это самая популярная платформа интерфейса в во всем мире и используется для создания приложений, начиная от сайтов электронной коммерции и заканчивая потоковыми платформами.

Поэтому можно с уверенностью сказать, что большинству веб-разработчиков, которые будут внедрять веб-SDK mParticle, не придется изучать React, прежде чем они смогут извлечь пользу из этого примера приложения.

Когда дело дошло до выбора шаблонов проектирования React, Алекс попытался найти баланс, отдав предпочтение относительно новым «встроенным» функциям, таким как React Hooks и Context Providers, а не Redux, сторонней библиотеке, которая широко распространена. известную стандартную архитектуру, но может быть очень громоздкой и сложной, чтобы в конечном итоге предоставить пользователю более понятный опыт обучения.

Например, использование настраиваемых хуков в течение достаточно долгого времени было тенденцией в сообществе React. Их использование влечет за собой создание собственных функций, использующих общие хуки React для совместного использования логики с отслеживанием состояния между компонентами.

Алекс считал, что использование этого подхода в примерах приложений помешало бы понять, как работает наш SDK, и по этой причине он решил придерживаться ванильных хуков, таких как useEffect.

«Если бы я создавал этот пакет как пакет, который кто-то будет использовать в своем проекте, я бы поступил немного по-другому, — говорит Алекс, — но поскольку это образовательный инструмент, я не хотел, чтобы кто-то беспокоился о что делает React — я хотел, чтобы они увидели, что mParticle делает в приложении React».

Изучая компоненты веб-приложения, вы увидите несколько примеров, в которых useEffect используется как для сбора атрибутов, которые будут пересылаться вместе с событиями mParticle, так и для запуска самих событий. Вот пример использования useEffect в компоненте ProductDetailPage:

```javascript

использоватьЭффект(() => {

// Генерирует подробное событие просмотра продукта, чтобы сигнализировать о том, что клиент

// просмотр сведений о продукте, что может привести к событию «Добавить в корзину»

если (продукт) {

// Создание объекта продукта mParticle перед отправкой любых событий электронной коммерции

const mParticleProduct: mParticle.Product = getMPProduct(product);

// Инициировать одно событие сведений о просмотре продукта электронной коммерции для этой страницы продукта

mParticle.eCommerce.logProductAction(

mParticle.ProductActionType.ViewDetail,

mParticleProduct,

// Если вы перерендерите и продукт изменится,

// это приведет к повторному запуску нового события сведений о просмотре продукта

}, [продукт]);

Использование хука vanilla React в таких случаях значительно упрощает понимание SDK mParticle, чем если бы эта логика была упакована в отдельные функции в разных модулях. Кроме того, вы можете заметить, что это пример кода с большим количеством комментариев.

Разработчики примера приложения не пожалели времени, чтобы четко прокомментировать код, связанный с использованием нашего SDK — как там, где происходят вызовы событий, так и во всей логике, поддерживающей сбор событий.

Вот еще один пример из того же компонента, показывающий, как комментарии помогают вам получить полный контекст того, как использовать наш SDK в реальных сценариях, и ничего не остается на догадки:

```javascript

// Рекомендуется использовать mParticle.createProduct при использовании нашего

// Функции ведения журнала электронной коммерции для генерации событий, чтобы вы могли

// обязательно правильно укажите все наши точки данных

const getMPProduct = (_product: Product): mParticle.Product => {

const {метка, идентификатор, цена} = _product;

// При передаче атрибутов в mParticle лучше не включать

// неопределенные или нулевые значения

константные атрибуты: mParticle.SDKEventAttrs = {};

если (цвет) {

атрибуты.цвет = цвет;

если (размер) {

атрибуты.размер = размер;

// В этом примере мы не работаем с несколькими брендами,

// категории и другие варианты использования для полноценной электронной коммерции

// заявление. Таким образом, мы передаем значение undefined для многих из этих

// атрибуты для выделения случаев, когда вам может понадобиться

// параметры, но не все.

вернуть mParticle.eCommerce.createProduct(

метка,

я бы,

цена,

parseInt(количество, 10),

undefined, // Вариант: используется для одиночных вариантов.

// Используйте пользовательские атрибуты для нескольких вариантов, таких как

// в этом случае использования

не определено, // Категория

не определено, // Торговая марка

не определено, // Позиция

undefined, // Код купона

атрибуты,

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

Проверка наших собственных SDK и функций и использование наших собственных продуктов

Хотя основная цель этих примеров приложений — помочь нашим клиентам легко внедрить наш SDK и извлечь выгоду из своих данных, мы также увидели большую внутреннюю ценность этих приложений как средства тестирования и улучшения — или «тестирования» — наших собственные SDK и функции, ориентированные на клиента.

Поиск ошибок в дебрях TypeScript

Например, создание примера веб-приложения позволило нам выявить некоторые пограничные случаи, возникающие при использовании нашего основного веб-SDK в проекте React с TypeScript в качестве пакета npm.

В некоторых случаях взаимодействие между этими тремя конкретными технологиями приводило к состоянию гонки, в котором наш SDK не всегда инициализировался при вызове события.

В то время как наш основной SDK уже содержал логику для решения этой проблемы, определенный код в пакетах React нарушил эти проверки и вызвал необычный каскад. Заметив эту проблему, Алекс отправился на поиски ошибок вместе с другим гуру JavaScript API Робом Ингом. Эти двое прочесали трассировку стека, исправили проблему и выпустили исправления для нашего основного SDK.

Использование собственных функций планирования данных

Несоответствия на этапе сбора данных являются одной из основных причин проблем с качеством данных в дальнейшем.

Инструменты и функции планирования данных mParticle разработаны, чтобы помочь инженерам и другим заинтересованным сторонам согласовать план данных, точно реализовать этот план и выявить ошибки в режиме реального времени.

Когда мы создавали эти примеры приложений, мы хотели практиковать то, что проповедуем, используя наши собственные инструменты планирования данных для обеспечения согласованности с как события и атрибуты именуются, структурируются и собираются на этих трех платформах.

Наши инженеры и менеджеры по проектам создали специальное рабочее пространство mParticle для проекта примеров приложений и использовали наш пользовательский интерфейс для создания и создания планов данных. После того, как события были реализованы во всех трех приложениях и мы начали отправлять события из SDK в mParticle, мы использовали Live Stream для проверки несоответствий между собранными и ожидаемыми данными, а также сообщения об ошибках Live Stream, чтобы легко отследить источник ошибок.

Использование этих функций значительно упростило процесс создания планов данных, реализации сбора событий и обеспечения согласованности между платформами. Наши собственные функции планирования данных оказали значительную помощь в создании примеров приложений, и мы планируем продолжать использовать примеры приложений для тестирования и улучшения наших функций планирования данных.

Что день грядущий?

Сокращая кривую обучения с помощью нашего SDK, ускоряя время внедрения и сокращая время окупаемости ваших данных, эти примеры приложений могут принести большую пользу инженерным командам, работающим с mParticle.

Тот факт, что мы выпустили наш MLP («Проект с минимальной привлекательностью», термин, который придумал наш премьер-министр Мэтт Бернье), знаменует собой начало, а не конец нашей работы по улучшению этих ресурсов.

«Я думаю, что это определенно то, во что мы будем продолжать инвестировать и улучшать со временем, — говорит Питер Дженкинс, — от добавления дополнительных комментариев до постоянного обновления с изменениями, которые мы вносим в SDK».

Кроме того, мы также намерены продолжать использовать эти приложения в качестве средства тестирования и улучшения не только наших функций SDK и API, но и всего нашего набора продуктов и функций.

Например, в следующих версиях веб-приложения мы планируем интегрировать наши инструменты разработчика, включая Smartype и Linting. Другими словами, эти примеры приложений будут, по словам Питера Дженкинса, «вечным источником документации о том, как именно использовать наш SDK, который вы действительно сможете запустить».

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

Ранее опубликовано здесь