Java | Pieowl

Pieowl doesn't ship a Java SDK. You send events from Java with a plain HTTP request to the Track API. The example below uses java.net.http.HttpClient, which is built into Java 11 and later. It works the same in Spring Boot, Quarkus, Micronaut or plain Java.

Before you start

You need a client ID and a client secret. Find them in the dashboard under Settings → Developers → Keys. Server requests must include the secret, so keep it on your server and load it from an environment variable.

Send an event

Every request is a POST to https://api.pieowl.com/track with a JSON body of { "type": ..., "payload": ... }.

Pieowl.java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.concurrent.CompletableFuture;

public final class Pieowl {
    private static final URI TRACK_URL = URI.create("https://api.pieowl.com/track");
    private static final HttpClient CLIENT = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build();

    // json is the full body, for example {"type":"track","payload":{...}}
    public static CompletableFuture<HttpResponse<String>> send(String json) {
        HttpRequest request = HttpRequest.newBuilder(TRACK_URL)
                .timeout(Duration.ofSeconds(5))
                .header("Content-Type", "application/json")
                .header("pieowl-client-id", System.getenv("PIEOWL_CLIENT_ID"))
                .header("pieowl-client-secret", System.getenv("PIEOWL_CLIENT_SECRET"))
                // Optional: forward the visitor's IP for location data
                // .header("pieowl-client-ip", visitorIp)
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        return CLIENT.sendAsync(request, HttpResponse.BodyHandlers.ofString());
    }
}

sendAsync doesn't block your request thread. Call .join() on the result if you need to wait.

The examples below write the JSON by hand to stay short. In a real app, build it with the JSON library you already use, like Jackson or Gson, so values are escaped correctly.

Usage

Tracking events

java

Pieowl.send("""
    {"type":"track","payload":{"name":"signup","profileId":"user_123","properties":{"plan":"pro"}}}
    """);

Identifying users

java

Pieowl.send("""
    {"type":"identify","payload":{"profileId":"user_123","firstName":"Joe","lastName":"Doe","email":"joe@doe.com","properties":{"tier":"premium"}}}
    """);

Incrementing and decrementing properties

value is optional and defaults to 1.

java

Pieowl.send("""
    {"type":"increment","payload":{"profileId":"user_123","property":"visits","value":1}}
    """);
Pieowl.send("""
    {"type":"decrement","payload":{"profileId":"user_123","property":"credits","value":1}}
    """);

Tracking revenue

A purchase is a revenue event with these properties:

__amount: in normal units, like 49.99, not cents.
__currency: an ISO 4217 code, like EUR. Optional, your site currency by default.
__orderId: your order number. The same order sent twice counts once.
__deviceId: the visitor's device ID, from pieowl.getDeviceId() in the browser. The purchase is credited to their visit.

For a refund, send the same event with __refund set to true. Leave out __amount to refund the whole order. See Revenue attribution.

java

Pieowl.send("""
    {"type":"track","payload":{"name":"revenue","properties":{"__amount":49.99,"__currency":"EUR","__orderId":"A-1001","__deviceId":"DEVICE_ID"}}}
    """);

// Refund the whole order
Pieowl.send("""
    {"type":"track","payload":{"name":"revenue","properties":{"__orderId":"A-1001","__refund":true}}}
    """);

The text blocks (""") need Java 15 or later. On Java 11, use normal strings.

Good to know

Errors: Pieowl answers with a 2xx status when it accepts a request. Check response.statusCode() and log anything else, for example a bad client secret or an invalid payload.
Kotlin: The same code works from Kotlin on the JVM. See the Kotlin page for an Android example.
More event types: Groups and the full request schema are in the Track API reference.