# Avo Inspector Java SDK

## Quick Start Guide

Find the Quick Start Guide in our [GitHub repo](https://github.com/avohq/java-avo-inspector).

## Installation

We host the library on JitPack.io, so

add the following to the root build.gradle:

```groovy
repositories {
    mavenCentral()
    ...
    maven { url 'https://jitpack.io' }
}
```

and:

```groovy
dependencies {
    debugImplementation 'com.github.avohq.java-avo-inspector:TAG'
}
```

Use the latest GitHub release tag to get the latest version of the library.

## Import

```java
import is.avo.inspector.AvoEventSchemaType;
import is.avo.inspector.AvoInspector;
import is.avo.inspector.AvoInspectorEnv;
```

## Initialization

Obtain the API key in Inspector tab in your [Avo.app](https://www.avo.app/welcome) workspace.

You will need to create an instance of `AvoInspector` with the constructor.

```java
public AvoInspector(@NotNull String apiKey, @NotNull String appVersion, @NotNull String appName, @NotNull AvoInspectorEnv env)
```

> #### Parameters:
>
> - `String apiKey` - the API key you get in Inspector tab of your Avo workspace
> - `String appVersion` - app version to attribute the events to
> - `String appName` - application name
> - `AvoInspectorEnv env` - current environment: AvoInspectorEnv.Dev, AvoInspectorEnv.Staging or AvoInspectorEnv.Prod

## Sending event schemas to Avo Inspector

This is the core of the **Avo Inspector SDK**.

Call \***\*one of the methods\*\*** in this section every time an event is tracked.

### Option 1

```java
@NonNull Map<String, AvoEventSchemaType> trackSchemaFromEvent(@NonNull String eventName, @Nullable JSONObject eventProperties);
// or
@NonNull Map<String, AvoEventSchemaType> trackSchemaFromEvent(@NonNull String eventName, @Nullable Map<String, ?> eventProperties);
```

> Example usage:
>
> ```java
> void trackEvent(@NonNull String eventName, @Nullable Map<String, ?> eventParams) {
>     tracker.track(eventName, eventParams);
>     this.avoInspector.trackSchemaFromEvent(eventName, eventParams);
> }
> ```

Extracts event schema from event properties represented by the second parameter (`JSONObject` or `Map<String, ?>`) and sends the schema to **Avo** for analysis.

> #### Parameters:
>
> - `String eventName` - event name, sometimes referred as event type.
> - `@Nullable JSONObject eventProperties` or `@Nullable Map<String, ?> eventProperties` - actual event properties, which will be converted to event schema on the device and the event schema will be sent to **Avo**. Resulting keys will be JSON fields keys and resulting values will be JSON fields values types converted to schema types.
>
> ##### Example format:
>
> ```java
> JSONObject eventProperties = new JSONObject();
> eventProperties.put("userId", 1337);
> eventProperties.put("emailAddress", "jane.doe@avo.app");
> eventProperties.put("key", "value");
> ```

> #### Return Type:
>
> - `@NonNull Map<String, AvoEventSchemaType>` containing event schema, so you can verify that conversion was correct.
>   Example format:
>
> ```java
> Map<String, AvoEventSchemaType> eventSchema = new HashMap<>();
> eventSchema.put("userId", new AvoEventSchemaType.AvoInt());
> eventSchema.put("emailAddress", new AvoEventSchemaType.AvoString());
> eventSchema.put("key", newAvoEventSchemaType.AvoString());
> ```

### Option 2

```java
void trackSchema(@NonNull String eventName, @Nullable Map<String, AvoEventSchemaType> eventSchema);
```

This method allows you to process the event schema before sending it.
It's handy to extract the schema from your event properties with `extractSchema(Object eventProperties)` (see below), process it and then provide it to this method.

> #### Parameters:
>
> - `@NonNull String eventName` - event name, also known as event type.
> - `@Nullable Map<String, AvoEventSchemaType> eventSchema` - actual event schema that will be sent to **Avo**.
>
> ##### Example format:
>
> ```java
> Map<String, AvoEventSchemaType> eventSchema = new HashMap<>();
> eventSchema.put("userId", new AvoEventSchemaType.AvoInt());
> eventSchema.put("emailAddress", new AvoEventSchemaType.AvoString());
> eventSchema.put("key", new AvoEventSchemaType.AvoString());
> ```

See [this](https://www.avo.app/docs/reference/avo-inspector-sdks/overview.md#standalone-usage) for details about event schema structure and schema types.

## Other methods

### 1. Extract schema from event properties

```
java @NonNull Map<String, AvoEventSchemaType> extractSchema(@Nullable Object eventProperties);`kotlin
fun extractSchema(eventProperties: Any?): Map<String, AvoEventSchemaType>
```

This is the method used by `trackSchemaFromEvent` internally. Extracts event schema in form of `Map<String, AvoEventSchemaType>` from an event properties object.

> #### Parameters:
>
> - `@Nullable Object eventProperties` - event properties object. If it is an instance of `JSONObject` or `Map<?, ?>` it will be processed based on the containing key-value pairs, otherwise the event schema will be based on object fields.

> #### Return Type:
>
> - `@NonNull Map<String, AvoEventSchemaType>` containing event schema of the given event properties. Keys are event properties names and values are event properties types.
>
> ##### Example format:
>
> ```java
> Map<String, AvoEventSchemaType> eventSchema = new HashMap<>();
> eventSchema.put("userId", new AvoEventSchemaType.AvoInt());
> eventSchema.put("emailAddress", new AvoEventSchemaType.AvoString());
> eventSchema.put("key", newAvoEventSchemaType.AvoString());
> ```

### 2. Print logs

```java
static void enableLogging(boolean enable); // static method on AvoInspector
```

`enableLogging` controls printing of tracked event schemas and other helpful information to logcat. Enabled by default in development environments.

> #### Parameters:
>
> - `boolean enable` - sets whether **Avo Inspector SDK** will print logs to the logcat.