Java SDK

Overview

The Journify Java SDK allows you to send tracking data from a Java application to the Journify backend. It simplifies the process of integrating your Java-based systems with Journify's infrastructure, enabling seamless event and user tracking. You can use this SDK to collect and forward data to various destinations such as Facebook Ads (via CAPI), Google Ads, Google Analtyics, CleverTap, and more.

Installation

You can install the SDK using Maven:

<dependency>
  <groupId>io.journify</groupId>
  <artifactId>journify-java-sdk</artifactId>
  <version>0.0.1</version>
</dependency>

Or using Gradle:

implementation 'io.journify:journify-java-sdk:0.0.1'

Initialization

Inside your app, you'll want to set your write_key before making any analytics calls, you can also add options during initialization:

import io.journify.analytics.Journify;

Journify journify = Journify.builder("YOUR_WRITE_KEY")
    .queueCapacity(1000)
    .flushIntervalInMillis(10000)
    .maximumFlushAttempts(3)
    .build();

Here are the available options:

Option key	Type	Description	Default value
flushQueueSize	int	The number of messages to enqueue before flushing.	250
flushIntervalInMillis	int	The number of milliseconds to wait before flushing the queue automatically.	10000
maximumFlushAttempts	int	The maximum number of attempts to flush a message before giving up.	3
maximumQueueSizeInBytes	int	The maximum size of the queue in bytes before blocking new messages.	512K Bytes
queueCapacity	int	The maximum number of messages that can be queued before blocking.	10000
forceTLsV1	boolean	Force the SDK to only support TLS v1 for secure connections.	false

API

The Journify Java SDK has two main methods for sending data to Journify: identify and track. Each method serves a different purpose and can be used to send different types of data.

Identify

The identify lets you record user traits. It includes a unique User ID and any optional traits you know about them.

Journify recommends that you call identify once when the user's account is created, and later when their traits change.

Example identify call:

Map<String, Object> traits = new LinkedHashMap<>();
traits.put("email", "[email protected]");
traits.put("firstname", "John");

journify.enqueue(IdentifyMessage.builder()
    .userId("user1234")
    .traits(traits)
    .build());

The identify call has the following fields:

Field	Description
userId String	The ID for this user in your database.
traits Map, optional	A map of traits you know about the user. Things like: email, firstname or lastname.
timestamp Date, optional	A Date object representing when the identify took place. This is most useful if you import historical data. If not specified, Journify will use the server's time.
anonymousId String, optional	An anonymous session ID for this user.

Track

track lets you record the actions your users perform. Every action can also have associated properties.

Example of events you might want to track include add_to_cart, purchase, or begin_checkout.

To get started, Journify recommends tracking all important events.

Example track call:

Map<String, Object> properties = new LinkedHashMap<>();
properties.put("currency", "USD");
properties.put("value", 29.99);

Map<String, Object> traits = new LinkedHashMap<>();
traits.put("email", "[email protected]");

journify.enqueue(TrackMessage.builder()
    .event("add_to_cart")
    .userId("user123")
    .properties(properties)
    .traits(traits)
    .build());

This call informs Journify that user123 just added a T-shirt to their cart.

The track method has the following fields:

FIELD	DESCRIPTION
userId String	The ID for this user in your database.
event String	The name of the event you're tracking. Use human-readable names like Song Played or Status Updated.
properties Map<String, Object>, optional	A map of properties for the event. If the event was Product Added, it might have properties like price or product.
timestamp Date, optional	A Date object representing when the track took place. This is most useful if you're importing historical data. If not specified, Journify will use the server's time.
anonymousId String, optional	An anonymous session ID for this user.
traits Map<String, Object>, optional	The traits of the user if available

Tips

Batching

Journify's libraries are built to support high-performance environments. It's safe to use the Java SDK in applications that process hundreds of requests per second.

Every method you call does not result in an HTTP request, but is queued in memory instead. Messages are flushed in batch in the background, which allows for much faster operation.

What happens if there are just too many messages?

If the SDK detects that it can't flush faster than it's receiving messages, it'll simply stop accepting messages. This means your program will never crash because of a backed-up queue. The default maximum queue size is configurable during initialization.

How do I flush events right now?!

You can also flush on demand. For example, at the end of your program, you'll want to flush to make sure there's nothing left in the queue. Just call the flush method:

journify.flush();

Calling this method will block the calling thread until there are no messages left in the queue. You'll want to use it as part of your cleanup scripts and avoid using it as part of the request lifecycle.

Source schema

When creating a source, it's required to attach a source schema that outlines which events and properties you are expecting to receive from this source. You can select a schema from our catalog or create a new one from scratch following the JSON Schema Draft-07 spec.

Troubleshooting

Common errors

So far, our customers haven't encountered any issues with this source. If anything unexpected comes up, feel free to contact us — we're ready to assist.

Live debugger

Journify provides complete visibility into what events you are receiving from the source once it's connected with Journify.