Просмотр кода страницы Настройка подключаемого модуля Astromkey Android Gradle для процессов инструментирования

Следующие параметры конфигурации позволяют настроить процесс инструментирования плагина Astromkey для Android Gradle.

== Конфигурации для конкретных вариантов ==
Плагин позволяет указать несколько конфигураций для конкретных вариантов, где каждая конфигурация для конкретного варианта может быть применена к нескольким вариантам сборки Android . Для каждого варианта необходимо указать конфигурацию для конкретного варианта. Если подключаемый модуль не может найти конкретную конфигурацию для определенного варианта сборки Android, он отменяет сборку и выдает ошибку. Эту функцию защиты можно отключить с помощью <code>strictMode</code>свойства.

Связь определяется регулярным выражением, указанным в свойстве <code>variantFilter</code>, и именем варианта сборки Android. Регулярное выражение чувствительно к регистру, и если вкус продукта не определен, тип сборки в имени варианта указывается в нижнем регистре. Если несколько конфигураций для конкретного варианта соответствуют одному и тому же варианту, выбирается и применяется первая конфигурация.

В следующем примере показано, как можно указать в <code>astromkey</code>блоке конфигурацию для конкретного варианта:

'''Groovy:'''
 <code>astromkey {
     configurations {
         dev {
             // build type name is upper case because a product flavor is used
             variantFilter "Debug"
             // other variant-specific properties
         }
         demo {
             // the first product flavor name is always lower case
             variantFilter "demo"
             // other variant-specific properties
         }
         prod {
             // build type name is upper case because a product flavor is used
             variantFilter "Release"
             // other variant-specific properties
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     configurations {
         create("dev") {
             // build type name is upper case because a product flavor is used
             variantFilter("Debug")
             // other variant-specific properties
         }
         create("demo") {
             // the first product flavor name is always lower case
             variantFilter("demo")
             // other variant-specific properties
         }
         create("prod") {
             // build type name is upper case because a product flavor is used
             variantFilter("Release")
             // other variant-specific properties
         }
     }
 }</code>
Например, у вас может быть приложение с двумя вариантами продукта, <code>demo</code>и <code>paid</code>, и двумя типами сборки по умолчанию, <code>debug</code>и <code>release</code>. Плагин можно использовать для указания конфигурации для всех вариантов отладочной сборки, <code>demoDebug</code>а <code>paidDebug</code>также двух других конфигураций для двух вариантов, <code>demoRelease</code>и <code>paidRelease</code>.

Связь между специфическими для варианта конфигурациями из плагина и вариантами сборки Android может быть напечатана вместе с задачей <code>printVariantAffiliation</code>. Например, в следующем примере показан вывод консоли из приведенного выше примера:
 <code>> Task :app:printVariantAffiliation
 Variant 'demoDebug' will use configuration 'dev'
 Variant 'demoRelease' will use configuration 'demo'
 Variant 'paidDebug' will use configuration 'dev'
 Variant 'paidRelease' will use configuration 'prod'</code>

=== Отдельные данные мониторинга разработки и производства ===
Если вы не хотите загрязнять данные производственного мониторинга данными мониторинга из ваших <code>debug</code>сборок, отделите данные разработки от данных производственного мониторинга.

Для этого создайте два мобильных приложения в Ключ-АСТРОМ. Создайте две конфигурации для конкретных вариантов и используйте предоставленные значения <code>applicationId</code>и <code>beaconUrl</code>со <code>Instrumentation</code>страницы.

'''Groovy:'''
 <code>astromkey {
     configurations {
         debug {
             variantFilter "[dD]ebug"
             autoStart {
                 applicationId '<DebugApplicationID>'
                 beaconUrl '<ProvidedBeaconURL>'
             }
         }
         prod {
             variantFilter "[rR]elease"
             autoStart {
                 applicationId '<ProductionApplicationID>'
                 beaconUrl '<ProvidedBeaconURL>'
             }
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     configurations {
         create("debug") {
             variantFilter("[dD]ebug")
             autoStart {
                 applicationId("<DebugApplicationID>")
                 beaconUrl("<ProvidedBeaconURL>")
             }
         }
         create("prod") {
             variantFilter("[rR]elease")
             autoStart {
                 applicationId("<ProductionApplicationID>")
                 beaconUrl("<ProvidedBeaconURL>")
             }
         }
     }
 }</code>
Если вы предпочитаете не отслеживать свои <code>debug</code>сборки, отключите конфигурацию для конкретного варианта, которая отвечает за ваши <code>debug</code>сборки.

'''Groovy:'''
 <code>astromkey {
     configurations {
         debug {
             variantFilter "[dD]ebug"
             enabled false
         }
         prod {
             variantFilter "[rR]elease"
             autoStart {
                 applicationId '<ProductionApplicationID>'
                 beaconUrl '<ProvidedBeaconURL>'
             }
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     configurations {
         create("debug") {
             variantFilter("[dD]ebug")
             enabled(false)
         }
         create("prod") {
             variantFilter("[rR]elease")
             autoStart {
                 applicationId("<ProductionApplicationID>")
                 beaconUrl("<ProvidedBeaconURL>")
             }
         }
     }
 }</code>

== Деактивация автоинструментария ==
Вы можете отключить автоинструментирование для всех вариантов или для определенного варианта.

=== Деактивация всех вариантов ===
Чтобы отключить автоинструментирование для всех вариантов, отключите плагин с помощью свойства <code>pluginEnabled</code>. Плагин по-прежнему добавляет ЕдиныйАгент SDK в качестве зависимости Gradle, чтобы гарантировать, что компилятор может скомпилировать исходные файлы, настроенные вручную.

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

Вы можете отключить автоинструментирование для всех вариантов или для определенного варианта.

'''Groovy:'''
 <code>astromkey {
     pluginEnabled false
     configurations {
         dev {
             // variant-specific properties
         }
         prod {
             // variant-specific properties
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     pluginEnabled(false)
     configurations {
         create("dev") {
             // variant-specific properties
         }
         create("prod") {
             // variant-specific properties
         }
     }
 }</code>

=== Деактивация одного варианта ===
Если вы хотите деактивировать автоматическое инструментирование для определенного варианта, явным образом деактивируйте конфигурацию для конкретного варианта с помощью свойства <code>enabled</code>. В следующем примере показано, как можно деактивировать все <code>debug</code>типы сборки (вариант <code>demoDebug</code>и <code>paidDebug</code>):

'''Groovy:'''
 <code>astromkey {
     configurations {
         dev {
             enabled false
             variantFilter "Debug"
         }
         prod {
             // variant-specific properties
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     configurations {
         create("dev") {
             enabled(false)
             variantFilter("Debug")
         }
         create("prod") {
             // variant-specific properties
         }
     }
 }</code>
''Пропуск автоинструментирования, если нет доступной конфигурации для конкретного варианта:''

Вы можете деактивировать это <code>strictMode</code>свойство и определить специфичную для варианта конфигурацию только для того варианта, который вы хотите инструментировать. Плагин не обрабатывает варианты сборки Android, если никакая конкретная конфигурация не соответствует данному варианту сборки Android.

Если вы не отключите <code>strictMode</code>свойство, плагин отменит сборку и выдаст ошибку. Мы не рекомендуем этот подход, поскольку функция строгого режима должна защитить вас от создания вариантов без конфигурации для конкретного варианта. Деактивируйте автоинструментирование с помощью <code>enabled</code>свойства конфигурации вашего варианта.

'''Groovy:'''
 <code>astromkey {
     strictMode false
     configurations {
         prod {
             variantFilter "Release"
             // other variant-specific properties
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     strictMode(false)
     configurations {
         create("prod") {
            variantFilter("Release")
            // other variant-specific properties
         }
     }
 }</code>

== Автозапуск инжектирования ==
Чтобы получить правильные параметры запуска, перейдите к мастеру инструментов в веб-интерфейсе Ключ-АСТРОМ.

# В меню Ключ-АСТРОМ выберите Mobile .
# Выберите мобильное приложение, которое вы хотите настроить.
# Выберите «Дополнительно » ( … ) > «Изменить» в правом верхнем углу плитки с названием вашего приложения.

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

# Выберите Android и перейдите на вкладку Groovy (build.gradle) или Kotlin (build.gradle.kts) .
# Используйте предварительно настроенный фрагмент (см. шаг « Применить плагин astromkey и добавьте конфигурацию плагина »), который уже заполнен значениями конфигурации из вашего мобильного приложения.

Все свойства, связанные с запуском ЕдиныйАгент, являются частью AutoStart DSL и должны быть настроены с помощью <code>autoStart</code>блока :

'''Groovy:'''
 <code>astromkey {
     configurations {
         sampleConfig {
             autoStart {
                 applicationId '<YourApplicationID>'
                 beaconUrl '<ProvidedBeaconURL>'
             }
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     configurations {
         create("sampleConfig") {
             autoStart {
                 applicationId("<YourApplicationID>")
                 beaconUrl("<ProvidedBeaconURL>")
             }
         }
     }
 }</code>
Функция автозапуска внедрения запускает ЕдиныйАгент в <code>Application.onCreate</code>методе. Если ваше приложение поддерживает прямую загрузку, вам необходимо отключить функцию автоматического запуска внедрения. Вы также должны прочитать Настройка связи с ЕдиныйАгент SDK для Android , чтобы убедиться, что ЕдиныйАгент может передавать данные в кластер.

=== Деактивация автозапуска инжектирования ===
Вы можете деактивировать функцию автоматического запуска инъекции с помощью <code>enabled</code>свойства. Вы не можете указать свойства <code>applicationId</code>и <code>beaconUrl</code>, поскольку эти значения должны использоваться при вызове запуска вручную.

'''Groovy:'''
 <code>astromkey {
     configurations {
         sampleConfig {
             autoStart.enabled false
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     configurations {
         create("sampleConfig") {
             autoStart.enabled(false)
         }
     }
 }</code>
Рекомендуется добавить в <code>Application.onCreate</code>метод вызов запуска. Дополнительные сведения см. в разделе ЕдиныйАгент SDK для Android > Запуск ЕдиныйАгент .

Дополнительные изменения конфигурации, указанные с помощью <code>astromkeyConfigurationBuilder</code>переопределения значений конфигурации, определенных с помощью DSL плагина astromkey для Android Gradle.

== Исключение определенных классов и методов ==
По умолчанию подключаемый модуль astromkey для Android Gradle обрабатывает все пакеты. Если вы хотите исключить определенные классы, у вас есть два варианта:

* Исключить список пакетов, классов и методов
* Использовать настраиваемый фильтр исключения

=== Исключить список пакетов, классов и методов с помощью свойств <code>packages</code>, <code>classes</code>и<code>methods</code> ===
'''Groovy:'''
 <code>astromkey {
     configurations {
         sampleConfig {
             exclude {
                 packages "com.mypackage", "com.another.example"
                 classes "com.example.MyClass"
                 methods "com.example.ExampleClass.exampleMethod", "com.example.ExampleClass\$InnerClass.anotherMethod"
             }
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     configurations {
         create("sampleConfig") {
             exclude {
                 packages("com.mypackage", "com.another.example")
                 classes("com.example.MyClass")
                 methods("com.example.ExampleClass.exampleMethod", "com.example.ExampleClass\$InnerClass.anotherMethod")
             }
        }
     }
 }</code>
Эти свойства содержат некоторые дополнительные функции:

* <code>packages</code>автоматически исключает подпакеты
* <code>classes</code>автоматически исключает внутренние классы
* <code>methods</code>автоматически исключает все методы с одинаковым именем (независимо от подписи метода)

Экранируйте <code>$</code>символ для внутренних классов, как показано в приведенном выше примере.

=== Использование настраиваемый фильтр исключения ===
Этот параметр позволяет определить более точную логику исключения с помощью дополнительных правил фильтрации. В фильтре вы можете определить регулярное выражение для <code>className</code>, <code>methodName</code>и <code>methodDescription</code>.

* Для <code>className</code>свойства используется полное имя.
* Имя класса совпадает, когда указанное выражение находится где-то в имени класса.
* Имя метода совпадает, когда указанное выражение находится где-то в имени метода.
* Описание метода совпадает , когда указанное выражение находится где-то в описании метода.

'''Groovy:'''
 <code>astromkey {
     configurations {
         sampleConfig {
             exclude {
                 // exclude all inner classes
                 filter {
                     className "\$"
                 }
 
                 // exclude all methods that fulfill this requirements
                 filter {
                     // the class is part of the "com.example" package
                     className "^com\\.example\\."
                     // the method name contain the phrase "webrequest" (uppercase notation is ignored for two letters)
                     methodName "[wW]eb[rR]equest"
                     // where the last parameter is a String and where the return value is void
                     methodDescription "Ljava/lang/String;\\)V"
                 }
             }
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     configurations {
         create("sampleConfig") {
             exclude {
                 // exclude all inner classes
                 filter {
                     className("\$")
                 }
 
                 // exclude all methods that fulfill this requirements
                 filter {
                     // the class is part of the "com.example" package
                     className("^com\\.example\\.")
                     // the method name contain the phrase "webrequest" (uppercase notation is ignored for two letters)
                     methodName("[wW]eb[rR]equest")
                     // where the last parameter is a String and where the return value is void
                     methodDescription("Ljava/lang/String;\\)V")
                 }
             }
         }
     }
 }</code>

== Настройка инструментария тестового примера ==
Плагин выполняет этап автоинструментации только при сборке приложения. Поэтому поведение локальных модульных тестов и инструментальных модульных тестов отличается.

=== Локальные модульные тесты ===

* Плагин Android Gradle версии 7.0.0+ Локальные модульные тесты используют инструментированные классы из вашей исходной папки, но неинструментированные библиотеки. Это не должно влиять на модульные тесты, так как подключаемый модуль в основном использует специфичные для Android классы и вызовы методов, которые игнорируются, когда ЕдиныйАгент не запущен. Это также справедливо для вызовов методов ЕдиныйАгент SDK.
* Версии подключаемого модуля Android Gradle 4.0.0–4.2.0. Локальные модульные тесты напрямую используют классы, сгенерированные компилятором Java или Kotlin, а этап автоматического инструментирования подключаемого модуля никогда не выполняется. Поскольку вызовы методов ЕдиныйАгент SDK помещаются в исходный код, они также доступны и выполняются в ваших локальных модульных тестах. Однако ЕдиныйАгент не запускается, а вызовы методов игнорируются.

=== Локальные модульные тесты с Robolectric ===
Robolectric позволяет имитировать Android в локальных модульных тестах.

* Плагин Android Gradle версии 7.0.0+ Robolectric использует инструментированные классы из вашей исходной папки, но неинструментированные библиотеки.
* Плагин Android Gradle версий 4.0.0–4.2.0 Robolectric использует классы, сгенерированные компилятором Java или Kotlin, которые не инструментированы автоматически.

Если вы отключили автозапуск внедрения и запустили ЕдиныйАгент вручную в <code>Application</code>классе, ЕдиныйАгент запускает и контролирует ваши тестовые случаи Robolectric. В этом случае скорректируйте конфигурацию, либо разделив данные мониторинга разработки и производства , либо используя другой тип сборки для модульных тестов .

=== Инструментальные модульные тесты ===
Для запуска инструментальных модульных тестов на устройстве или эмуляторе сборка Android создает два APK-файла:

* APK-файл приложения, которое вы хотите протестировать. Плагин является частью этого процесса сборки и автоматически обрабатывает APK-файл.
* Тестовый APK-файл, содержащий класс для тестирования другого APK. Плагин также является частью этого процесса сборки, но он не выполняет автоматическую настройку этих тестовых APK.

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

=== Использование другого типа сборки для модульных тестов ===
Для индивидуального поведения инструментовки для ваших модульных тестов создайте новый тип сборки для ваших модульных тестов с помощью подключаемого модуля.

'''Groovy:'''
 <code>android {
     buildTypes {
         // build type used for unit tests in the CI
         CI {
             initWith debug
             applicationIdSuffix ".debugTesting"
         }
     }
 }</code>
'''Kotlin:'''
 <code>android {
     buildTypes {
         // build type used for unit tests in the CI
         create("CI") {
             initWith(getByName("debug"))
             applicationIdSuffix = ".debugTesting"
         }
     }
 }</code>
Например, если вы хотите отслеживать свои <code>debug</code>сборки, используемые разработчиками, и не хотите отслеживать выполнение модульного теста в CI, используйте следующую конфигурацию:

'''Groovy:'''
 <code>astromkey {
     configurations {
         developer {
             variantFilter "[dD]ebug"
             autoStart {
                 applicationId '<DebugApplicationID>'
                 beaconUrl '<ProvidedBeaconURL>'
             }
         }
         ciTesting {
             // deactivate instrumentation for CI tests
             variantFilter "CI"
             enabled false
         }
         prod {
             variantFilter "[rR]elease"
             autoStart {
                 applicationId '<ProductionApplicationID>'
                 beaconUrl '<ProvidedBeaconURL>'
             }
         }
     }
 }</code>
'''Kotlin:'''
 <code>configure<com.astromkey.tools.android.dsl.astromkeyExtension> {
     configurations {
         create("developer") {
             variantFilter("[dD]ebug")
             autoStart {
                 applicationId("<ProductionApplicationID>")
                 beaconUrl("<ProvidedBeaconURL>")
             }
         }
         create("ciTesting") {
             // deactivate instrumentation for CI tests
             variantFilter("CI")
             enabled(false)
         }
         create("prod") {
             variantFilter("[rR]elease")
             autoStart {
                 applicationId("<DebugApplicationID>")
                 beaconUrl("<ProvidedBeaconURL>")
             }
         }
     }
 }</code>
Когда вы выполняете модульные тесты с <code>debug</code>вариантом, модульные тесты отслеживаются, поскольку инструментирование деактивируется только для <code>CI</code>варианта.