С приходом Compose в голове всё чаще всплывают мысли, что же ещё можно написать в декларативном стиле. И как мне кажется, на эту роль хорошо подходит аналитика, точнее, описание её событий. В среде разработчиков тема аналитики нечасто всплывает в обсуждениях. Отправка аналитики не является целью фичи, а лишь обязательной дополнительной частью. Сама отправка — задача довольно тривиальная и поэтому воспринимается обычно как «обязаловка», а не как интересный процесс, в котором можно блеснуть своими знаниями архитектуры. Тем не менее, если сложить время всех задач по отправке аналитики, то получится довольно приличное количество часов. Поэтому хочется, чтобы работа с этой частью была максимально комфортной. В этом и поможет декларативный подход.

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

Вводные

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

В нашем случае одна — что-то из популярного, вроде Google Analytics или Yandex Metrika. Вторая — самописная аналитика внутри компании, которая предоставляет данные для отдела машинного обучения, например, чтобы более качественно и быстро выдать пользователю рекомендации. События одни и те же, но в разные аналитики уходит разный набор параметров.

Когда-то давно у нас всё было построено на константах и выглядело примерно так:

class OldAnalytics(
   private val currentTimeProvider: CurrentTimeProvider,
   private val analytics1: Analytics1,
   private val analytics2: Analytics2
) {

   fun sendEvent(userId: Int, itemsIds: List<Int>) {
       val analytics1Params = mutableMapOf<String, String>()
       analytics1Params[FEATURE] = SOME_FEATURE
       analytics1Params[SCREEN] = SOME_SCREEN
       analytics1Params[BLOCK] = SOME_BLOCK
       analytics1Params[ACTION] = CLICK
       analytics1Params[REASON] = SOME_REASON
       analytics1Params[USER_ID] = userId.toString()
       analytics1Params[ITEM_IDS] = itemsIds.joinToString()
       val time = currentTimeProvider.getCurrentTime().toString()
       analytics1Params[CURRENT_TIME] = time
       analytics1.send("SomeEventName", params = analytics1Params)

       val analytics2Params = mutableMapOf<String, String>()
       analytics1Params[SCREEN] = SOME_SCREEN
       analytics2Params[SOURCE] = "SomeSource"
       analytics2Params[ACTION] = CLICK
       analytics2.send("SomeEventName", params = analytics2Params)
   }

   companion object {

       const val FEATURE = "feature"
       const val SCREEN = "screen"
       const val BLOCK = "block"
       const val ACTION = "action"
       const val REASON = "reason"
       const val SOURCE = "source"
       const val SOME_FEATURE = "SomeFeature"
       const val SOME_SCREEN = "SomeScreen"
       const val SOME_BLOCK = "SomeBlock"
       const val SOME_REASON = "SomeReason"
       const val CLICK = "Click"
       const val USER_ID = "userId"
       const val ITEM_IDS = "itemIds"
       const val CURRENT_TIME = "currentTime"
   }
}

Я специально привёл такой большой кусок кода, чтобы вы могли ощутить всю монструозность такого подхода. А ведь это только одно событие. Помимо количества кода, в таком подходе есть ещё целый ворох проблем:

• Целое полотно из констант, в которых уже через 5-10 событий можно ориентироваться только через поиск. По всему приложению событий аналитики сотни (возможно и за тысячу перевалило, но это не точно). Всё это счастье в одном очень-очень большом файле. 

• Для многих событий нужно «обогащение» данными, когда в событие нужно добавить информацию, которой сейчас нет на экране. Из-за этого приходилось в Presenter/ViewModel добавлять зависимости, которые нужны исключительно для отправки событий в аналитику. 

• В этих константах легко запутаться. Часто получалось, что какая-то константа использовалась, например, в 15 событиях. В новых требованиях аналитики её содержимое нужно поменять, но только в 14 событиях. Хорошо, если разработчик это заметил. Но часто бывало, что разработчик не замечал этого, и в одном из событий аналитики отправлялось неверное значение или ключ. 

• Константы типа String, в целом не очень удобное решение. Иногда константы, предназначенные для конкретного ключа, например, «Screen» использовались с другими ключами, например, «Block». При этом с точки зрения кода и Lint всё было хорошо. Опять же, при изменении значения константы иногда ломалось значение у параметра с совершенно другим ключом.

• Сборка события происходит в том же потоке, в каком был вызван метод отправки. Это почти всегда был main. В итоге отправка аналитики била по скорости работы приложения.

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

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

Требования

Мы решили попробовать сделать события аналитики с помощью декларативного подхода. Чтобы больше не возится с константами. Ну, почти… 

Мы выработали следующие требования к нашей будущей аналитике:

• Простота. Хочется, чтобы писать аналитику было довольно просто, без лишних заморочек.

• Читаемость. Хочется, чтобы когда ты смотришь аналитику, которую делал другой разработчик, например, на Pull Request’е, то всё было понятно.

• Производительность. Хочется, чтобы отправка аналитики никак не влияла на общую производительность приложения, так как события аналитики отправляются в приложении постоянно, и часто приходится для создания события делать какие-либо операции.

• Обогащение. Не всегда на экране, с которого должны уходить события аналитики, есть все данные, необходимые для конкретного события. Не хочется портить логику, связанную с экраном, то есть код Presenter/ViewModel, какой-либо логикой, связанной с аналитикой.

• Многомодульность — хорошая работа с многомодульностью. Чтобы в общих модулях не было значений, относящихся к конкретным модулям.

Создание общей модели

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

В итоге родились два data-класса, описывающие события аналитики. По одному на каждую аналитику.

data class Analytics1Event(
   val eventName: String,
   val feature: String?,
   val screen: String?,
   val block: String?,
   val action: String?,
   val reason: String?,
   val additionalParams: Map<String, Any?>?
)

data class Analytics2Event(
   val eventName: String,
   val screen: String?,
   val source: String?,
   val action: String?,
)

Собственно, в обоих моделях обязательным является только eventName. Остальные могут отсутствовать в некоторых событиях. Также в модели для первой аналитики присутствует property под названием additionalParams. Туда предполагается складывать параметры, которые ситуативны для события. 

Вместо констант в ключах у нас теперь property в модели. Теперь настало время что-то придумать и с константами в значениях.

Типы параметров

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

Начнём с интерфейса. Вместо просто String у нас появляются следующие типы-интерфейсы: AnalyticsAction, AnalyticsScreen, AnalyticsFeature, AnalyticsBlock. Каждый из которых относится к своему параметру аналитики. Рассмотрим только AnalyticsAction. Ибо он первый под руку попался. Остальные устроены похожим образом.

interface AnalyticsAction : Parcelable {

   val key: String
}

По сути, он просто содержит в себе одно property типа String. Задача этого интерфейса — просто не давать типам параметров аналитики путаться между собой. Вместо AnalyticsAction уже не подсунуть, например, AnalyticsScreen. Проще говоря, не дать разработчику засунуть параметр не того типа.

Сами же значения хранятся в отдельных фичёвых enum.

@Parcelize
enum class CommonAnalyticsAction(
   override val key: String
): AnalyticsAction {

   CLICK("Click"),
   LONG_CLICK("LongClick"),
   OPEN("Open"),
   CLOSE("Close"),
}

@Parcelize
internal enum class Feature1AnalyticsAction(
   override val key: String
): AnalyticsAction {

   RECEIVE("Receive"),
}

«Почему бы не сделать просто enum? Зачем их несколько, да ещё и interface?». Всё дело в многомодульности. В нашем проекте базовые классы аналитики находятся в базовом модуле base-analytics, который подключается к фичёвым модулям.

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

В подходе с «interface с несколькими enum» в модуле base-analytics содержатся только общий interface AnalyticsAction и его наследник — общий enum CommonAnalyticsAction, в котором содержатся реально общие значения, не относящиеся прямо ни к одной из фичей. Если же фича должна иметь собственные значения, то в фичёвом модуле содержится её собственный enum, в котором хранятся относящиеся только к ней значения. Кстати, не лишним будет пометить этот enum в Kotlin как internal.

Но что, если значение будет уникальным не только для фичи, но и для события. Если оно используется только в одном единственном событии и больше нигде, то для этого предусмотрен класс CustomAnalyticsAction:

@Parcelize
data class CustomAnalyticsAction(
   override val key: String
) : AnalyticsAction

В нужном месте будет достаточно прописать:

CustomAnalyticsAction("customAction")

И у вас появилось уникальное значение. Это также актуально, если значение создаётся на основе runtime данных приложения.

CustomAnalyticsAction("customAction$actionType")

Общая модель и типы у нас есть. Теперь надо как-то заполнить эту модель с помощью декларативного подхода.

Решение выглядит не очень эффективным с точки зрения потребления памяти. Либо используются значения enum, либо создаются объекты. В целом так и есть, с использованием строк было бы эффективнее. Но в этом конкретном месте было решено немного сжать рамки для разработчиков не позволяя добавлять значения одного типа в другой тип. Тем самым сделать код немного безопаснее за счёт того, что перепутать типы уже никак нельзя. Да и важность оптимизаций именно в этом месте не очень велика. Относительно современных объёмов оперативной памяти такое потребление ничего особо не поменяет.

Декларативность

В общем смысле декларативный подход в Kotlin основан на Type-safe builders, позволяющих нам делать собственные DSL. Правда, сами разработчики Kotlin называют это полудекларативным подходом («semi-declarative way»). Но нам не очень важно, кто, что и как называет. Главное, что общий подход выглядит следующим образом.

class SemiDeclarativeWay {

   fun code() = html {
   }
}

Под капотом html представляет из себя обычную функцию, которая в качестве аргумента принимает лямбду c receiver. В роли receiver выступает какой-либо объект.

fun html(init: HTML.() -> Unit): HTML {
    val html = HTML()
    html.init()
    return html
}

Использование лямбды с receiver позволит нам внутри этой лямбды обратиться к receiver (HTML) как к this. За счёт этого у нас выстраивается вложенность объектов, и нам нет необходимости обращаться к экземпляру HTML через переменную. 

Дело за малым. Осталось переложить эти знания на нашу аналитику. Создаём интерфейс EventBuilder, наследники которого будут описывать конкретные события аналитики.

interface EventBuilder {

   fun buildEvent(): AnalyticsEvent

   fun event(init: AnalyticsEvent.() -> Unit): AnalyticsEvent {
       val analyticsEvent = AnalyticsEvent()
       analyticsEvent.init()
       return analyticsEvent
   }
}

В нём всего два метода:

• buildEvent создаёт наше событие аналитики (AnalyticsEvent);

• event позволит заполнить содержимое AnalyticsEvent в декларативном стиле.

На данной стадии событие выглядит как-то так:

internal class DeclarativeEventBuilder: EventBuilder {

   override fun buildEvent() = event {
   }
}

То же самое теперь надо провернуть с самим AnalyticsEvent. Чтобы была возможность заполнить и его поля в декларативном стиле.

class AnalyticsEvent {

   private var analytics1Event: Analytics1EventDeclarative? = null
   private var analytics2Event: Analytics2EventDeclarative? = null

   fun analytics1(
       init: Analytics1EventDeclarative.() -> Unit
   ): Analytics1EventDeclarative {
       val eventDeclarative = Analytics1EventDeclarative()
       eventDeclarative.init()
       analytics1Event = eventDeclarative
       return eventDeclarative
   }

   fun analytics2(
       init: Analytics2EventDeclarative.() -> Unit
   ): Analytics2EventDeclarative {
       val eventDeclarative = Analytics2EventDeclarative()
       eventDeclarative.init()
       analytics2Event = eventDeclarative
       return eventDeclarative
   }
}

В нём у нас будет два метода: для первой аналитики — analytics1 и для второй — analytics2. Работает каждый из них со своим объектом, так как в разные аналитики у нас уходит свой набор данных.

Представлять аналитики будут два класса: Analytics1EventDeclarative и Analytics2EventDeclarative. В них, по сути, провернем тоже самое — сделаем заполнение полей через декларативный подход. 

Весь их код я приводить не буду. При желании можете посмотреть его под спойлером.

class Analytics1EventDeclarative {

   var eventName: String? = null
   var action: AnalyticsAction? = null
   var reason: String? = null
   private var source: EventSourceDeclarative? = null
   private var additional: EventAdditionalDeclarative? = null

   fun source(
       block: EventSourceDeclarative.() -> Unit
   ): EventSourceDeclarative {
       val eventDeclarative = EventSourceDeclarative()
       block(eventDeclarative)
       source = eventDeclarative
       return eventDeclarative
   }

   fun additional(
       block: EventAdditionalDeclarative.() -> Unit
   ): EventAdditionalDeclarative {
       val additionalDeclarative = EventAdditionalDeclarative()
       additionalDeclarative.block()
       additional = additionalDeclarative
       return additionalDeclarative
   }

   fun customAction(customAction: String): AnalyticsAction {
       return CustomAnalyticsAction(customAction)
   }

   fun build(): Analytics1Event {
       return Analytics1Event(
           eventName = this.eventName!!,
           feature = this.source?.feature?.key,
           screen = this.source?.screen?.key,
           block = this.source?.block?.key,
           action = this.action?.key,
           reason = this.reason,
           additionalParams = this.additional?.params
       )
   }

   class EventSourceDeclarative {

       var feature: AnalyticsFeature? = null
       var screen: AnalyticsScreen? = null
       var block: AnalyticsBlock? = null

       fun customFeature(customFeature: String): AnalyticsFeature {
           return CustomAnalyticsFeature(customFeature)
       }

       fun customScreen(customScreen: String): AnalyticsScreen {
           return CustomAnalyticsScreen(customScreen)
       }

       fun customBlock(customBlock: String): AnalyticsBlock {
           return CustomAnalyticsBlock(customBlock)
       }
   }

   class EventAdditionalDeclarative {

       var params: Map<String, Any?>? = null

       fun <T> fromPair(vararg items: Pair<String, T?>): Map<String, T?> {
           return mapOf(*items)
       }
   }
}

class Analytics2EventDeclarative {

   var eventName: String? = null
   var screen: String? = null
   var source: String? = null
   var action: AnalyticsAction? = null

   fun customAction(customAction: String): AnalyticsAction {
       return CustomAnalyticsAction(customAction)
   }

   fun build(): Analytics2Event {
       return Analytics2Event(
           eventName = this.eventName!!,
           screen = this.screen,
           source = this.source,
           action = this.action?.key,
       )
   }
}

Взглянем же, наконец, на итоговый пример заполнения события аналитики в декларативном стиле. Для примера создадим класс SomeEventBuilder, который описывает отправку какого-то события на каком-то экране.

internal class SomeEventBuilder(
   private val userId: Int,
   private val itemsIds: List<Int>,
   private val timestampProvider: () -> Long
) : EventBuilder {

   override fun buildEvent() = event {
       analytics1 {
           eventName = "SomeEventName"
           reason = "SomeReason"
           action = CommonAnalyticsAction.CLICK
           source {
               feature = Feature1AnalyticsFeature.FEATURE_1
               screen = Feature1AnalyticsScreen.FEATURE_1_SCREEN
               block = customBlock("SomeBlock")
           }
       }
       analytics2 {
           eventName = "SomeName"
           source = "SomeBlockOfUser$userId"
           action = customAction("Click")
           screen = Feature1AnalyticsScreen.FEATURE_1_SCREEN
       }
   }
}

Как по мне, неплохо. Мне всё понятно, но это ощущение субъективно. Вы можете поиграться с вложенностью, пока не получите результат, который нравится лично вам. 

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

additional {
   params = fromPair(
       "userId" to userId,
       "itemIds" to itemsIds.joinToString(),
       "currentTime" to timestampProvider()
   )
}

Сам класс SomeEventBuilder лежит в фичёвом модуле. Таким образом, вся аналитика распределяется по модулям.

Ещё один момент: вы можете обратить внимание, что параметр eventName не является обязательным в декларативном методе, но обязателен в модели для аналитики. Всё из-за того, что в Kotlin DSL пока нет возможности помечать поля как required. Я тут вижу три варианта: 

• Подождать, пока создатели Kotlin допилят Kotlin Contracts. Они обещали.

• Воспользоваться сторонним решением.  

• Обязательные параметры передавать как параметры метода, как это происходит в Compose. Хотя мне это не очень нравится с эстетической точки зрения. Вот смотрите:

internal class DeclarativeEventBuilder : EventBuilder {

   override fun buildEvent() = event {
       analytics1(
           eventName = "SomeEventName"
       ) {
           action = CommonAnalyticsAction.CLICK
       }
   }
}

Можно заметить, что из объявленных в начале требований декларативный подход к событиям закрывает три из них: простота, понятность, многомодульность. Остались ещё два: обогащение и производительность. Начнём с первого.

Обогащение

Допустим, для нашего события нужно дополнительно послать какую-то информацию, например, о текущем времени. Я знаю, что System.currentTimeMillis() статический, и ситуация не очень реалистичная, но это просто для примера. На его месте может быть что угодно — от информации о пользователе до списка предыдущих экранов. При этом на самом экране и в Presenter/ViewModel, из которого и будет отправляться событие, текущее время не нужно.

Если пытаться отправлять события напрямую из Presenter, то придётся добавлять в его конструктор сущность, которая предоставит информацию для аналитики. Затем перед отправкой события доставать из него текущее время. Пусть этой сущностью будет CurrentTimeProvider:

class SomePresenter
@Inject constructor(
   private val featureAnalytics: FeatureAnalytics,
   private val timeProvider: CurrentTimeProvider
) {

   fun onSomeClick() {
       val currentTime = timeProvider.getTime()
       featureAnalytics.onSomeClick(currentTime)
   }
}

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

Чтобы этого избежать, мы создали класс-прослойку <Feature>Analytics. Который и служит цели обогащения данных для аналитики и инкапсуляции аналитики в целом.

В примере с текущим временем мы в конструктор новоявленного класса FeatureAnalytics добавляем CurrentTimeProvider и будем отдавать текущее время в обратном вызове SomeEventBuilder.

class FeatureAnalytics(
   private val analyticsSender: AnalyticsSender,
   private val timeProvider: CurrentTimeProvider
) {

   fun sendEvent(userId: Int, itemsIds: List<Int>) {
       val builder = SomeEventBuilder(
           userId = userId,
           itemsIds = itemsIds,
           timestampProvider = timeProvider::getCurrentTime
       )
       analyticsSender.send(builder)
   }
}

А зачем здесь пробрасывается метод timeProvider::getCurrentTime? Почему бы не вызвать его перед созданием SomeEventBuilder и не передать значение сразу в конструктор? 

Во-первых, нужно, чтобы вызов происходил во время создания AnalyticsEvent, а не в тот момент, когда создаётся его Builder.

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

Также лучше не позволять SomeEventBuilder обращаться к зависимостям напрямую. Например, когда SomeEventBuilder обращается CurrentTimeProvider за текущим временем.

internal class SomeEventBuilder(
   private val userId: Int,
   private val itemsIds: List<Int>,
   private val timeProvider: CurrentTimeProvider
) : EventBuilder { ... }

Пусть он делает это через лямбду в конструкторе.

internal class SomeEventBuilder(
   private val userId: Int,
   private val itemsIds: List<Int>,
   private val timestampProvider: () -> Long
) : EventBuilder { ... }

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

Но вернёмся к прослойкам <Feature>Analytics. С помощью такой прослойки Presenter не засоряется логикой, связанной с аналитикой. В целом использование прослойки — дело дискуссионное, ведь не всегда нужно обогащать события. Тут всё зависит от вашей аналитики. Если события часто обогащаются дополнительными данными, то стоит задуматься. Если же нет, то и от такой прослойки смысла тоже нет.

<Feature>Analytics классы также хранятся в feature модулях. В итоге вся аналитика, связанная с фичёй, остаётся в фичёвом модуле.

Займёмся последним требованием: производительность.

Производительность

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

По сути вся работа над производительностью сводится к тому, чтобы вызвать декларативный метод в отдельном потоке. Так как объект аналитики, описанный в декларативном методе, создаётся только при его вызове, то само создание <Some>Builder класса является быстрой задачей, а более долгий метод создания объекта аналитики вызывается в выделенном для аналитики потоке. С помощью таких простых манипуляций мы освободим наш главный поток от аналитики.

По этой же причине стоит превращать данные из моделей для Presentation или бизнес-логики в данные для аналитики прямо внутри метода создания объекта аналитики. Это сэкономит драгоценное время вашего главного потока.

Переход на другой поток, вызов декларативного метода и отправка данных в аналитику происходят внутри AnalyticsSender.

AnalyticsSender переходит на отдельный поток, вызывает buildEvent, тем самым собирая событие и передаёт его в классы, каждый из которых отвечает за свою аналитику Analytics1Sender и Analytics2Sender. 

Внутри них происходит конвертация из объектов, которыми мы оперируем, в формат, понимаемый библиотекой аналитики.

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

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

Надеюсь, кому-то из вас такой подход тоже пришелся по душе и в мире станет больше аналитики с использованием декларативного подхода.