Settings

Overview

In order to decrease duplication and give the user possibility to turn off specific default behaviour, the GanalyticsSettings was introduced. Currently there are 4 cases when settings can come to help:

1. When user have to use Prefix for many actions with always same splitter
2. When for overall analytics some specific NamingConvention is applied. (small bonus: in settings is not necessary to define one of conventions from NamingConventions enumeration, any implementation of NamingConvention interface is acceptable)
3. When it is necessary to keep Ananlytics prefix for category
4. When you need to define set of label converters in one place

Settings

Prefix Splitter

When it is needed to keep for actions category prefix, the @Prefix annotation can be used. But there are cases, when prefix and action must be split with some prefix. When in most or all cases same splitter is used, it is allowed to define it in global settings.

For example:

interface SomeInterface1 {
    @Prefix(splitter = "_") fun method1();
    fun method2();
}

interface SomeInterface1 {
    fun method1();
    @Prefix(splitter = "_") fun method2();
}

will produce next events:

Event(category = "someinterface1", action = "someinterface1_method1")
Event(category = "someinterface1", action = "method2")
Event(category = "someinterface2", action = "method1")
Event(category = "someinterface2", action = "someinterface2_method2")

When prefixSplitter in global settings is set to "_" then first snippet will be changed to:

interface SomeInterface1 {
    @Prefix fun method1();
    fun method2();
}

interface SomeInterface1 {
    fun method1();
    @Prefix fun method2();
}

Thus, the duplication will be eliminated

Naming Convention

There are some cases when it is needed to use one global naming convention for all Category and Group interfaces. Then setting namingConvention can be used.

Note: if there is only one group interface and it is needed to use convention from standard pack then @Convention annotation can be applied to single group interface.

Main advantages of usage namingConvention settings compare to group interface annotation, is:

1. Ability to use several group interfaces without duplicating annotation
2. Ability to use completely custom naming convention (currently it is not possible throw annotation)

Disabling cutting off Analytics prefix

By default for all interfaces that have Analytics prefix in their name, this prefix is cutting off. The exception will be explicit declaration of category name through @Category annotation:

For example:

interface AnalyticsInterface {
    fun method();
}

will transform to Event(category = "interface", action = "method"). But:

@Category("analyticsinterface")
interface AnalyticsInterface {
   fun method();
}

will transform to Event(category = "analyticsinterface", action = "method")

So, there are cases when Analytics prefix must be stayed. One of major is unexpected default behavior. For the possibility to disable cutting off unnecessary Analytics prefix, cutOffAnalyticsClassPrefix is introduced. By default it is true. When it is set to false then Analytics prefix will remain, thus, no need to put explicit @Category annotations (for above snippet of code)

Type converters for labels

From documentation of @Label annotation it is known, that user can explicitly point how to convert passing argument to appropriate label through special LabelConverter implementation.

But there are cases, when a lot of labels with same type are passed as parameters through different methods. Moreover, there are situations, when it is more appropriate to gather all converters in one place instead of passing each one in its own position.

Besides, when implementation of LabelConverter is passed through annotation, it has to meet the next requirements:

1. Be defined in explicit class
2. Has an object declaration or empty constructor

In some cases it is not acceptable, that's why labelTypeConverters setting is introduced. There are three main usage of that setting:

1. PlusAssign and Plus operators

labelTypeConverters += TypeConverterPair<DummyDataClass> { it.name } +
                        TypeConverterPair<DummyReversedClass> { it.id.toString() } +
                        (DummyClass::class.java to TypeConverter<DummyClass> { it.name })

2. Varargs

labelTypeConverters = converters(
                DummyDataClass::class.java to TypeConverter<DummyDataClass> { it.name },
                DummyReversedClass::class.java to TypeConverter<DummyReversedClass> { it.id.toString() },
                TypeConverterPair<DummyClass> { it.name })

3. For java users

settings
        .addTypeConverter(DummyDataClass.class, DummyDataClass::getName)
        .addTypeConverter(DummyReversedClass.class, it -> String.valueOf(it.getId()))
        .addTypeConverter(DummyClass.class, DummyClass::getName);

By default, if for Type A introduced LabelConverter implementation through settings, then for type B (which is subtype to A) this converter will be applied, if there is no registered converter for type B and there is no converter through @Label annotation. To disable that default behavior, useTypeConvertersForSubType must be set to false.

Example

Below an example of formulating GanalyticsSettings is shown (in Kotlin):

GanalyticsSettings {
    cutOffAnalyticsClassPrefix = false
    prefixSplitter = "_"
    namingConvention = NamingConventions.LOWER_SNAKE_CASE
    useTypeConvertersForSubType = false
    labelTypeConverters += TypeConverterPair<DummyDataClass> { it.name } +
            TypeConverterPair<DummyReversedClass> { it.id.toString() } +
            TypeConverterPair<DummyClass> { it.run { "$id.$name" } }
}