Please reach out to MetaRouter before testing or implementing this library.

Overview

This library lets you record analytics data from your Java code. Once installed, the requests will be sent to the MetaRouter platform and then sent to the integrations you have configured for your pipeline that is connected to your Java events.

You can use the Java library in your web server controller code. It is built for high performance and uses and internal queue to make all calls non-blocking and fast. It will batch messages and flush asynchronously to the MetaRouter platform.

Install the Library

We recommend installing the library with a build system like Maven. If you do it this way, you will have much less trouble upgrading your SDK when necessary.

The library is distributed as a jar dependency via Maven Central. Here's what it would look like with Maven.

Add to pom.xml:

<dependency>
    <groupId>io.metarouter.analytics.Java</groupId>
    <artifactId>analytics</artifactId>
    <version>LATEST</version>
</dependency>

Initialize the SDK

Before you can start sending us events, you will need to initialize an instance of the Analytics class. Do this using the Analytics.builder class, inputting the writeKey for your Java pipeline.

Analytics analytics = Analytics.builder("YOUR_writeKey")
        .endpoint("YOUR_INGESTION_URL")
        .build();

Note that an internal AnalyticsClient class exists, and should not to be confused with the public Analytics class.

The Analytics class has a method called enqueue that takes a MessageBuilder. Each message class has a corresponding builder that is used to construct instances of a message. Be sure to provide either a userId or anonymousID for each message, as failing to do so will raise an exception at runtime.

Required SDK Edits

In the above SDKs, there are three places where you will need to add information custom to your MetaRouter implementation. Instructions for setting up your DNS, which includes the Ingestion URL that you will insert into your SDK setup, can be found here. Your writeKey will indicate the specific pipeline you would like to feed your events into.

Event Methods in Java

Check out the below calls and their use cases to determine the event calls that you need to make. We have also included examples of how you would call specific objects in Java. For general guidance on when to use the available event methods, please see this guide.

Note: The following examples use the Guava immutable map style, but feel free to use standard Java maps instead.

Identify

The identify method helps you associate your users and their actions to a unique and recognizable userID and any optional traits that you know about them. We recommend calling an identify a single time - when the user's account is first created and only again when their traits change.

analytics.enqueue(IdentifyMessage.builder()
    .userId("qwerty1234")
    .traits(ImmutableMap.builder()
        .put("name", "Buzz Aldrin")
        .put("email", "[email protected]")
        .put("gender", "male")
        .put("title", "Second person to visit the moon")
        .build()
    )
);

The above call identifies Buzz by his unique userID and labels him with name, email, gender, and title traits.

Track

To get to a more complete event tracking analytics setup, you can add a track call to your website. This will tell MetaRouter which actions you are performing on your site. With track, each user action triggers an event, which can also have associated properties.

analytics.enqueue(TrackMessage.builder("Item Purchased")
    .userId("qwerty1234")
    .properties(ImmutableMap.builder()
        .put("revenue", 50.00)
        .put("shipping", "Next-Day")
        .build()
    )
);

The above call tells us that someone has purchased an item for 50 dollars and has selected a Next-Day shipping option.

Screen

Note: The screen call pulls the same data as a page call, but is used for mobile rather than web sources.

analytics.enqueue(ScreenMessage.builder("MoonLanding")
    .userId("qwerty1234")
    .properties(ImmutableMap.builder()
        .put("category", "Space")
        .put("path", "/space/moonlanding")
        .build()
    )
);

The above call tells us that someone has viewed a MoonLanding page that is categorized in a Space section of a mobile app.

Group

The group method associates an identified user with a company, organization, project, etc.

analytics.enqueue(GroupMessage.builder("some-group-id")
    .userId("qwerty1234")
    .traits(ImmutableMap.builder()
        .put("name", "MetaRouter")
        .put("size", 55)
        .put('website", "www.metarouter.io")
        .build()
    )
);

The above call assigns the user with the "MetaRouter" group and gives that group the size and website traits.