Привет! Мы написали свою систему диплинков на основе кодогенерации. В этой статье поговорим, как мы упростили работу с диплинками и смогли отловить устаревшие, добавили мониторинг и как собрали все диплинки в одной статье в конфлюенсе.

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

Самая большая проблема — это проблема безопасности. Объясню на примере активити, которая открывает веб-страницы. Активити открывается по диплинку, в нём указывается URL в качестве параметра. Один из вариантов атаки — когда злоумышленник может заставить пользователя пройти по диплинку с URL на вредоносный сайт и таким образом провести атаку. Ещё одна из возможных проблем — на некоторых экранах нам нужно валидировать параметры, а это иногда занимает значительную часть активити. Было бы хорошо вынести валидацию в отдельное место.

Ещё у нас бывали случаи, когда маркетинг запускал промо-кампании либо с диплинками, в которых содержались ошибки, либо с устаревшими диплинками, которые уже не поддерживались, и мы могли об этом даже и не узнать. А при заведении новой кампании маркетинг обращался к разработчиками за диплинками и поиск занимал некоторое время. Если разработчик помнил название экрана и диплинк без параметров, то его можно было быстро найти, а если название экрана сразу не вспомнилось, то алгоритм поиска примерно такой: сбилдить проект -> пройти на нужный экран -> посмотреть в логах, какая активити открылась -> пойти в манифест для получения диплинка -> открыть исходных код активити для сбора входных параметров.

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

Пример объявления диплинка для экрана бонуса.

@DeepLink(
   Uri("qiwi", "bonus"),
   description = Description("открыть раздел бонус(кэшбек)")
)
class BonusHandler : ProxyDeepLinkHandler() {
   override val activityClass: Class<*> = BonusShowcaseActivity::class.java
}

С помощью аннотации @Deeplink помечаем обработчик и задаем диплинк, в данном примере диплинк qiwi://bonus откроет BonusShowcaseActivity.

Во втором примере показано, как производим проверки перед открытием диплинка.

@DeepLink(
   Uri("qiwi", "bonus"),
   description = Description("открыть раздел бонус(кэшбек)")
)
class BonusHandler : DeepLinkHandler() {

   @Inject
   lateinit var bonusShowcaseFeature: BonusShowcaseFeature

   override fun deeplinkData(context: Context, intent: Intent): DeepLinkData {
       QiwiApplication.get(context)
           .appComponent.inject(this)
       val clazz = BonusShowcaseActivity::class.java
       val startIntent = Intent(context, claszz).copyIntent(intent)
       return bonusShowcaseFeature.deepLinkData(DeepLinkData(startIntent, claszz))
   }
}

В обработчике проверяем фича флаг BonusShowcaseFeature и открываем экран, если флаг включен. Про наши фича флаги можно почитать в этом посте.

Аннотации

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.SOURCE)
annotation class DeepLink(
   vararg val deepLinks: Uri,
   val description: Description = Description(),
   val commonParams: Array<Parameter> = [],
   val addToDoc: Boolean = true
)

@Retention(AnnotationRetention.SOURCE)
annotation class Uri(
   val scheme: String,
   val hostPath: String,
   val description: Description = Description(),
   val parameters: Array<Parameter> = [],
   val examples: Array<Example> = [],
   val addToDoc: Boolean = true
)

@Retention(AnnotationRetention.SOURCE)
annotation class Description(
   val description: String = "",
   val group: String = Groups.OTHER
)

@Retention(AnnotationRetention.SOURCE)
annotation class Parameter(
   val key: String = "",
   val value: String = "",
   val description: String = ""
)

@Retention(AnnotationRetention.SOURCE)
annotation class Example(
   val description: String,
   val parameters: Array<Parameter> = []
)

Сейчас в системе у нас пять аннотаций.

Deeplink — используется для описания одно или нескольких uri, также есть возможность добавить описание, общие параметры для всех uri и можно указать, попадёт ли данный диплинк в документацию.
Uri — позволяет установить диплинк(scheme://hostPath), дополнительно можно оставить описание, параметры, с которыми используется диплинк, и, если необходимо, добавить примеры.
Description— используется для описания. Можно указать группу, в которой содержится диплинк, это необходимо для сортировки в итоговой документации.
Parameter— аннотация задаёт query-параметры в формате key-value, в value описываем возможные значения.
Example — используется для примеров.

Аннотация Deeplink указывает, какой обработчик будет обрабатывать диплинк из аннотации Uri. Все обработчики являются наследниками класса DeepLinkHandler.

class DeepLinkData(
   val startIntent: Intent?,
   val activityClazz: Class<*>?
)

abstract class DeepLinkHandler {

   var analytics: DeepLinkHandlerAnalytics? = null

   abstract fun deeplinkData(context: Context, intent: Intent): DeepLinkData

   fun process(context: Context, intent: Intent) {
       val deepLinkData = deeplinkData(context, intent)
       deepLinkData.startIntent?.let { startIntent ->
           context.startActivity(startIntent)

       }
   }
}

Абстрактный класс, который умеет открывать активити по интенту и отправлять аналитику. При наследовании от этого класса нужно реализовать метод deeplinkData и в нём можно проводить обработку диплинка.

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

abstract class ProxyDeepLinkHandler : DeepLinkHandler() {

   protected abstract val activityClass: Class<*>

   override fun deeplinkData(context: Context, intent: Intent): DeepLinkData {
       val startIntent = Intent(context, activityClass).copyIntent(intent)
       return DeepLinkData(startIntent, activityClass)
   }
}

При наследовании от этого класса в дочернем классе достаточно определить поле activityClass, который должен возвращать ту активити, которую нужно открыть.

Архитектура диплинков

Под капотом всё работает немного сложнее. Точкой входа у нас является SplashActivity. Она с помощью DeepLinkDelegate и остальных компонентов достаёт из реестра нужный обработчик для того диплинка, который пришёл в систему.

Манифест для SplashActivity выглядит следующим образом.

<activity
   android:name=".splashScreen.view.SplashScreenActivity"
   android:theme="@style/QiwiSplashScreenTheme">
   <intent-filter>
       <action android:name="android.intent.action.VIEW" />

       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />

       <data android:scheme="qiwi" />
   </intent-filter>
   <intent-filter>
       <action android:name="android.intent.action.VIEW" />

       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />

       <data android:scheme="http" />
       <data android:scheme="https" />

       <data android:host="qiwi.com" />
       <data android:host="qiwi.ru" />

       <data android:path="/main.action" />
       ...
       <data android:pathPattern="/p/.*" />
       <data android:path="/feed" />
   </intent-filter>
</activity>

В манифесте есть два интент-фильтра для диплинков. Первый для диплинков — со схемой qiwi, что позволяет открывать любые диплинки с этой схемой. Во втором интент-фильтр используется для url-диплинков. Мы редко добавляем url-диплинки, поэтому манифест практически не редактируем.

Кодогенерация

Во время кодогенерации происходит поиск всех классов, помеченных аннотацией Deeplink, потом с помощью Kotlin Poet создаются несколько DeeplinkRegistry и json-файл с описанием диплинков для документации.

DeeplinkRegistry — это интерфейс с методом registry(), возвращающий мапу, где ключ - диплинк, а значение — класс обработчика.

Пример сгенерированного DeeplinkRegistry для диплинков uri:

public class OuterDeepLinkRegistryGenerated : DeepLinkRegistry {
   public override fun registry(): Map<String, Class<out Any>> {
       val map = mutableMapOf<String, Class<out Any>>()
       map["qiwi://bonus"] = BonusHandler::class.java
       map["qiwi://main.action"] = MainHandler::class.java
       map["qiwi://cards/detail"] = CardDetailActivityHandler::class.java
       ...
       map["qiwi://help"] = ProfileActivityHandler::class.java
       return map
   }
}

Json-файл с описанием диплинков выглядит так:

{
 "qiwi://bonus": {
   "description": "открыть раздел бонус(кэшбек)"
 },
 "qiwi://qvc/order": {
   "group": "QIWI-карты",
   "description": "заказ qvc или qvc_mir карты",
   "parameters": [
     {
       "name": "alias",
       "value": "qvc | qvc-mir"
     }
   ]
 },
 "qiwi://cards/detail": {
   "group": "QIWI-карты",
   "description": "детали карты",
   "parameters": [
     {
       "name": "id",
       "value": "*",
       "description": "id карты"
     }
   ]
 }
}

Из этого файла создается документация.

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

Таблица всегда актуальная, так как выгрузка json-файла встроена в релизный пайплайн. С помощью таски файл загружается на статик-сервер. А в конфлюенсе настроена таблица, которая подгружает и парсит json-файл.

Таблица в первую очередь полезна отделу маркетинга, так как позволяет быстро получить инфу по диплинкам.

В системе диплинков мы добавили мониторинг и аналитику. И получаем события о необработанных диплинках. Алерты настроены на почту и в телеграм-канал, что позволяет быстро реагировать на инциденты.

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

Итоги

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

We need to go deeper: диплинки и кодогенерация