Annotations

Welcome to a wiki page. Ganalytics is a library to simplify your work with analytics in app. Here you can find list of all currently supported annotations with their descriptions:

@Category

When we have too long named interface or category name must be named completely different from interface name (for example, they have different naming conventions), then @Category annotation comes to help use. Currently, it's very simple. When you want to specify a name of @Category for all actions, you need to mark you category-interface with this annotation and pass the desired name to it. Scope: interface, method, property(since 1.1).

@Action

When we have too long named method in interface or action name must be named completely different from method name (for example, they have different naming conventions), then @Action annotation comes to help use. Currently, it's very simple. When you want to specify a name of @Action for concrete method, you need to mark you action-method with this annotation and pass the desired name to it. Scope: method.

@HasPrefix

Annotation used when you want to add prefixes for your action in an interface. Scope: method, interface, property(since 1.1). When this annotation used on method then prefix applies only to it. When @HasPrefix used on an interface, then settings of this annotation applies to all methods of interface (expect methods that already have such annotation or methods with annotation @NoPrefix).

It has two parameters:

1. name - exactly title of prefix for using. It is not required field. If it will not be specified, then the name of the category will be applied. For example:

   interface SomeCategory {
      @HasPrefix("cat") fun someAction()
   }

   will produce category = "somecategory" and action = "catsomeaction"

   And

   interface SomeCategory {
      @HasPrefix fun someAction()
   }

   will produce category = "somecategory" and action = "somecategorysomeaction"

2. splitter - you can specify delimiter between prefix and action. For example:

   interface SomeCategory {
      @HasPrefix("cat", splitter = "-") fun someAction()
   }

   will produce category = "somecategory" and action = "cat-someaction"

Note: @HasPrefix without name will use name of category as prefix.

@NoPrefix

In case when @HasPrefix used on interface (or method/property in Group Interface) for some methods you don't want to use prefix. In this case @NoPrefix can help. For example:

@HasPrefix
interface SomeCategory {
   fun action1()
   @NoPrefix fun action2()
}

will produce two events:

1. category = "somecategory" and action = "somecategoryaction1"
2. category = "somecategory" and action = "action2"

Scope: method, interface, property(since 1.1)

@HasPostfix

(since 1.1)

Annotation used when you want to add postfixes for your action in an interface. Scope: method, interface, property. When this annotation used on method then postfix applies only to it. When @HasPostfix used on an interface, then settings of this annotation applies to all methods of interface (expect methods that already have such annotation or methods with annotation @NoPostfix).

It has two parameters:

1. name - exactly title of postfix for using. It is required field. For example:

   interface SomeCategory {
      @HasPostfix("cat") fun someAction()
   }

   will produce category = "somecategory" and action = "someactioncat"

   But

   interface SomeCategory {
      @HasPostfix fun someAction()
   }

   will not compile

2. splitter - you can specify delimiter between action and postfix. For example:

   interface SomeCategory {
      @HasPrefix("cat", splitter = "-") fun someAction()
   }

   will produce category = "somecategory" and action = "someaction-cat"

Note: @HasPostfix (unlike @HasPrefix) will not use category as postfix when name is not specified (since it is required field).

@NoPostfix

(since 1.1)

In case when @HasPostfix used on interface (or method/property in Group Interface) for some methods you don't want to use postfix. In this case @NoPostfix can help. For example:

@HasPostfix("postfix")
interface AnalyticsCategory {
   fun action()
   @NoPostfix fun otherAction()
}

will produce two events:

1. category = "category" and action = "actionpostfix"
2. category = "category" and action = "otheraction"

Scope: method, interface, property

@Label

For determining whether an output Event should include label or value (besides category and action), the @Label annotation and set of rules must be used:

1. A method of analytics interface must has a zero, one or two parameters. If there are more than two parameters, then an appropriated error will be shown.
2. If method has zero arguments, then output Event will have label = "" and value = 0
3. If method has one argument, then it automatically be a label
4. If method has two arguments, but none of them is Number, then appropriated error will be thrown (since value must be a Number and there is not numbers in parameter list of method, then value can not be retrieved)
5. If method has two arguments, and one of them is Number without @Label annotation, then this argument will be automatically handled as value and remain one will be handled as label (whether it has @Label annotation or not)
6. If method has two arguments, and both of them are Number without @Label annotation, then first one will be a label and second one will be a value

Also custom LabelConverter can be specified. Note that it must be an kotlin object or have empty constructor. Otherwise UndeclaredThrowableException will be thrown. If LabelConverter or @Label annotation are not specified for argument, then simple toString() will be invoked.

Also there is more specific interface TypedLabelConverter, for LabelConverter that handled for some specific type of arguments. These small rules are applied to it:

1. If an argument has same type or it is subtype of type specified in TypedLabelConverter, then everything is good.
2. If an argument has different type than in TypedLabelConverter, then ClassCastException will be thrown.

@LabelFun

@Convention

By default all class names and method names are converted to lower case according category and action. For example, SimpleAnalyticsInterface class name will converted to simpleanalyticsinterface category. To give some control over that process, the @Convention annotation is introduced. Scope: interface, method, property(since 1.1) Currently only predefined naming conventions are available for that annotation:

1. UPPER_SNAKE_CASE: SimpleAnalyticsInterface -> Simple_analytics_interface
2. LOWER_SNAKE_CASE: SimpleAnalyticsInterface -> simple_analytics_interface
3. UPPER_CAMEL_CASE: SimpleAnalyticsInterface -> SimpleAnalyticsInterface
4. LOWER_CAMEL_CASE: SimpleAnalyticsInterface -> simpleAnalyticsInterface
5. LOWER_CASE: SimpleAnalyticsInterface -> simpleanalyticsinterface

Also, global convention may be specified in global settings. Any custom convention may be defined here.