From db6e3305faac7b30ab4a1ad9d4eda9c5923d4cfd Mon Sep 17 00:00:00 2001 From: caseyamp Date: Tue, 22 Mar 2022 14:29:18 -0700 Subject: [PATCH 1/3] Adding java sdk --- docs/analytics/sdks/java-sdk.md | 237 ++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 238 insertions(+) create mode 100644 docs/analytics/sdks/java-sdk.md diff --git a/docs/analytics/sdks/java-sdk.md b/docs/analytics/sdks/java-sdk.md new file mode 100644 index 000000000..ba489f2f8 --- /dev/null +++ b/docs/analytics/sdks/java-sdk.md @@ -0,0 +1,237 @@ +--- +title: Java SDK +description: +icon: fontawesome/brands/java +--- + +The backend Java SDK (separate from Android) + +???info "SDK Resources" + - [Java SDK Reference :material-book:](http://amplitude.github.io/Amplitude-Android/) + - [Java SDK Repository :material-github:](https://github.com/amplitude/Amplitude-Java) + - [Java SDK Releases :material-code-tags-check:](https://github.com/amplitude/Amplitude-Java/releases) + +--8<-- "includes/ampli-vs-amplitude.md" + +## SDK Installation + +### Maven + +Use Gradle or another build system to resolve the Java SDK dependency. The following example is for Gradle: + +```java +dependencies { + implementation 'org.json:json:20201115' + implementation 'com.amplitude:java-sdk:1.6.1' +} +``` + +### Download (alternative) + +Download the [latest JAR file](https://github.com/amplitude/Amplitude-Java/releases) and add it to the project's buildpath. See instructions for your IDE. + +## EU Data Residency + +Sending data to Amplitude's EU servers, you need to configure the server URL during the initialization. + +```java +Amplitude amplitude = Amplitude.getInstance(); +amplitude.init("API KEY"); +amplitude.setServerUrl("https://api.eu.amplitude.com/2/httpapi"); +``` + +## Usage & Examples + +### Importing + +Import Amplitude into any file that uses it. Amplitude uses the open source `JSONObject` library to conveniently create JSON key-value objects. + +```java +import com.amplitude.Amplitude; +import org.json.JSONObject; +``` + +### Initialization + +Initialization is necessary before any instrumentation is done. The API key for your Amplitude project is required. + +```java +Amplitude client = Amplitude.getInstance(); +client.init("YOUR_API_KEY"); +``` + +`Amplitude.getInstance(String name)` may optionally take a name which uniquely holds settings. + +```java +Amplitude client = Amplitude.getInstance("YOUR_INSTANCE_NAME"); +client.init("YOUR_API_KEY"); +``` + +### Configure batching behavior + +To support high performance environments, our SDK send events in batch. Every event logged by `logEvent` method is queued in memory. Events are flushed in batch in background. There are two properties Amplitude can use to customize batching behavior. + +```java +Amplitude client = Amplitude.getInstance(); +// events queued in memory will flush when number of events exceed upload threshold +// default value is 10 +client.setEventUploadThreshold(20); + +// events queue will flush every certain milliseconds based on setting +// default value is 10,000 milliseconds +client.setEventUploadPeriodMillis(5000); +``` + +Events can also be flushed on demand. + +```java +client.flushEvents(); +``` + +For customers who want to send large batches of data at a time, for example through scheduled jobs, rather than in a continuous realtime stream, we provide the batch mode. Both the regular mode and the batch mode use the same events upload threshold and flush time intervals, but the batch mode allows larger payload size(20MB) and has higher throttling limit. Due to the higher rate of data that's permitted by this mode, data sent by batch mode may be delayed based on load. You can see a usage example in [this project](https://github.com/amplitude/Amplitude-Java/blob/main/src/demo/java/com/demo/amplitude/LocalUploadDemo.java) on GitHub. + +```java +// Enable batch mode +client.useBatchMode(true); + +// Disable batch mode +client.useBatchMode(false); +``` + +## Sending Events + +Events represent how users interact with your application. For example, "Button Clicked" may be an action you want to track. + +!!!note + + For testing Java SDK out, please make sure your main thread continues until the background daemon thread that has the Amplitude HTTP request is finished. Otherwise, the main thread terminated earlier than the daemon thread will lead `logEvent` to fail silently. + +```java +Amplitude client = Amplitude.getInstance(); +client.logEvent(new Event("Button Clicked", "test_user_id")); +``` + +### Events with Properties + +Events can also contain properties. They provide context about the event taken. For example, "hover time" may be a relevant event property to "button click." + +```java +Event event = new Event("Button Clicked", "test_user_id"); + +JSONObject eventProps = new JSONObject(); +try { + eventProps.put("Hover Time", 10).put("prop_2", "value_2"); +} catch (JSONException e) { + System.err.println("Invalid JSON"); + e.printStackTrace(); +} + +event.eventProperties = eventProps; + +client.logEvent(event); +``` + +### Set User Properties + +!!!warning "Privacy and tracking' + + Please be sure to not track any user data that may be against your privacy terms. + +Use `event.userProperties` as a shorthand to set multiple user properties at once. + +```java +Event event = new Event("Button Clicked", "test_user_id"); + +JSONObject userProps = new JSONObject(); +double[] arr = {1,2,4,8}; +try { + userProps.put("team", "red").put("running_times", arr); +} catch (JSONException e) { + e.printStackTrace(); + System.err.println("Invalid JSON"); +} + +event.userProperties = userProps; +client.logEvent(event); +``` + +### Set Device Information + +Unlike the Android SDK or iOS SDK, device information in Java SDK isn't collected via SDK. Device information like device id, device brand, device manufacturer, and device model can be set as properties in each event. + +```java +Event event = new Event("Button Clicked", "test_user_id"); +event.deviceId = "device_id"; +event.deviceBrand = "device_brand"; +event.deviceManufacturer = "device_manufacturer"; +event.deviceModel = "device_model"; +client.logEvent(event); +``` + +### Set Session Information + +You can set `sessionId` in an event. This pattern also applies to other properties like `city` and `price`. You can see a full list of events properties in [Event.java](https://github.com/amplitude/Amplitude-Java/blob/main/src/main/java/com/amplitude/Event.java). + +```java +Event event = new Event("Button Clicked", "test_user_id"); +event.sessionId = 1; +client.logEvent(event); +``` + +### Amplitude Callbacks + +Support for AmplitudeCallBacks is available beginning with 1.4.0. You can trigger a callback when event is sent to server or failed after retries. + +```java +Amplitude client = Amplitude.getInstance(); +AmplitudeCallbacks callbacks = + new AmplitudeCallbacks() { + @Override + public void onLogEventServerResponse(Event event, int status, String message) { + // Event: Event processed. + // status: response code, like 200, 400, etc. + // message: success or error message. + } +}; +client.setCallbacks(callbacks); +``` + +From 1.5.0, callbacks can be added to event level and triggered when the event is sent to server or failed after retries. One event can trigger both client level callbacks and event level callbacks. + +```java +Amplitude client = Amplitude.getInstance(); +AmplitudeCallbacks eventCallbacks = + new AmplitudeCallbacks() { + @Override + public void onLogEventServerResponse(Event event, int status, String message) { + // Event: Event processed. + // status: response code, like 200, 400, etc. + // message: success or error message. + } +}; +client.logEvent(event, eventCallbacks) +``` + +### Middleware + +Middleware allows you to extend Amplitude by running a sequence of custom code on every event. This pattern is flexible and can be used to support event enrichment, transformation, filtering, routing to third-party destinations, and more. + +Each middleware is a simple interface with a run method: + +```java +void run(MiddlewarePayload payload, MiddlewareNext next); +``` + +The `payload` contains the `event` being sent as well as an optional `extra` that allows you to pass custom data to your own Middleware implementations. + +To invoke the next middleware in the queue, use the `next` function. You must call `next.run(payload)` to continue the middleware chain. If a middleware doesn't call `next`, then the event processing stop executing after the current middleware completes. + +Middleware is added to Amplitude via `client.addEventMiddleware`. You can add as many middleware as you like. Each middleware runs in the order in which it was added. + +You can find examples for [Java](https://github.com/amplitude/ampli-examples/blob/main/jre/java/AmpliApp/src/main/java/org/example/LoggingMiddleware.java) and [Kotlin](https://github.com/amplitude/ampli-examples/blob/main/jre/kotlin/AmpliApp/src/main/kotlin/LoggingMiddleware.kt). + +## Troubleshooting + +When debugging, check the logs. The SDK prints error messages. + +If you have problems, open an issue on the [GitHub issues page](https://github.com/amplitude/Amplitude-Java/issues). diff --git a/mkdocs.yml b/mkdocs.yml index a6b5b3408..fbd2d462d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -149,6 +149,7 @@ nav: - Amplitude SDKs: - analytics/sdks/android-sdk.md - analytics/sdks/sdk-javascript-overview.md + - analytics/sdks/java-sdk.md - Experiment: - experiment/index.md - Data: From 9cbe7ac1408ec810746b5d65dd987dc23468e505 Mon Sep 17 00:00:00 2001 From: caseyamp Date: Tue, 22 Mar 2022 14:42:54 -0700 Subject: [PATCH 2/3] minor updates to Java SDK --- docs/analytics/sdks/java-sdk.md | 36 ++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/docs/analytics/sdks/java-sdk.md b/docs/analytics/sdks/java-sdk.md index ba489f2f8..e289fb2b5 100644 --- a/docs/analytics/sdks/java-sdk.md +++ b/docs/analytics/sdks/java-sdk.md @@ -13,7 +13,7 @@ The backend Java SDK (separate from Android) --8<-- "includes/ampli-vs-amplitude.md" -## SDK Installation +## SDK installation ### Maven @@ -30,7 +30,7 @@ dependencies { Download the [latest JAR file](https://github.com/amplitude/Amplitude-Java/releases) and add it to the project's buildpath. See instructions for your IDE. -## EU Data Residency +## EU data residency Sending data to Amplitude's EU servers, you need to configure the server URL during the initialization. @@ -40,7 +40,7 @@ amplitude.init("API KEY"); amplitude.setServerUrl("https://api.eu.amplitude.com/2/httpapi"); ``` -## Usage & Examples +## Usage and examples ### Importing @@ -69,7 +69,7 @@ client.init("YOUR_API_KEY"); ### Configure batching behavior -To support high performance environments, our SDK send events in batch. Every event logged by `logEvent` method is queued in memory. Events are flushed in batch in background. There are two properties Amplitude can use to customize batching behavior. +To support high performance environments, our SDK sends events in batches. Every event logged by `logEvent` method is queued in memory. Events are flushed in batch in background. You can customize batch behavior with `setEventUpdloadThreshfold` and `setEventUploadPeriodMillis`. ```java Amplitude client = Amplitude.getInstance(); @@ -82,13 +82,15 @@ client.setEventUploadThreshold(20); client.setEventUploadPeriodMillis(5000); ``` -Events can also be flushed on demand. +You can also flush events on demand. ```java client.flushEvents(); ``` -For customers who want to send large batches of data at a time, for example through scheduled jobs, rather than in a continuous realtime stream, we provide the batch mode. Both the regular mode and the batch mode use the same events upload threshold and flush time intervals, but the batch mode allows larger payload size(20MB) and has higher throttling limit. Due to the higher rate of data that's permitted by this mode, data sent by batch mode may be delayed based on load. You can see a usage example in [this project](https://github.com/amplitude/Amplitude-Java/blob/main/src/demo/java/com/demo/amplitude/LocalUploadDemo.java) on GitHub. +For customers who want to send large batches of data at a time, for example through scheduled jobs, rather than in a continuous real-time stream, Amplitude provides the batch mode. + Both the regular mode and the batch mode use the same events upload threshold and flush time intervals, but the batch mode allows larger payload size(20MB) and has higher throttling limit. + Due to the higher rate of data that's permitted by this mode, data sent by batch mode may be delayed based on load. You can see a usage example in [this project](https://github.com/amplitude/Amplitude-Java/blob/main/src/demo/java/com/demo/amplitude/LocalUploadDemo.java) on GitHub. ```java // Enable batch mode @@ -98,7 +100,7 @@ client.useBatchMode(true); client.useBatchMode(false); ``` -## Sending Events +## Sending events Events represent how users interact with your application. For example, "Button Clicked" may be an action you want to track. @@ -111,7 +113,7 @@ Amplitude client = Amplitude.getInstance(); client.logEvent(new Event("Button Clicked", "test_user_id")); ``` -### Events with Properties +### Events with properties Events can also contain properties. They provide context about the event taken. For example, "hover time" may be a relevant event property to "button click." @@ -131,13 +133,13 @@ event.eventProperties = eventProps; client.logEvent(event); ``` -### Set User Properties +### Set user properties !!!warning "Privacy and tracking' Please be sure to not track any user data that may be against your privacy terms. -Use `event.userProperties` as a shorthand to set multiple user properties at once. +Use `event.userProperties` as a shorthand to set multiple user properties at one time. ```java Event event = new Event("Button Clicked", "test_user_id"); @@ -155,7 +157,7 @@ event.userProperties = userProps; client.logEvent(event); ``` -### Set Device Information +### Set device information Unlike the Android SDK or iOS SDK, device information in Java SDK isn't collected via SDK. Device information like device id, device brand, device manufacturer, and device model can be set as properties in each event. @@ -168,7 +170,7 @@ event.deviceModel = "device_model"; client.logEvent(event); ``` -### Set Session Information +### Set session information You can set `sessionId` in an event. This pattern also applies to other properties like `city` and `price`. You can see a full list of events properties in [Event.java](https://github.com/amplitude/Amplitude-Java/blob/main/src/main/java/com/amplitude/Event.java). @@ -178,7 +180,7 @@ event.sessionId = 1; client.logEvent(event); ``` -### Amplitude Callbacks +### Amplitude callbacks Support for AmplitudeCallBacks is available beginning with 1.4.0. You can trigger a callback when event is sent to server or failed after retries. @@ -214,7 +216,8 @@ client.logEvent(event, eventCallbacks) ### Middleware -Middleware allows you to extend Amplitude by running a sequence of custom code on every event. This pattern is flexible and can be used to support event enrichment, transformation, filtering, routing to third-party destinations, and more. +Middleware allows you to extend Amplitude by running a sequence of custom code on every event. + This pattern is flexible and can be used to support event enrichment, transformation, filtering, routing to third-party destinations, and more. Each middleware is a simple interface with a run method: @@ -222,9 +225,10 @@ Each middleware is a simple interface with a run method: void run(MiddlewarePayload payload, MiddlewareNext next); ``` -The `payload` contains the `event` being sent as well as an optional `extra` that allows you to pass custom data to your own Middleware implementations. +The `payload` contains the `event` being sent as well as an optional `extra` that allows you to pass custom data to your own middleware implementations. -To invoke the next middleware in the queue, use the `next` function. You must call `next.run(payload)` to continue the middleware chain. If a middleware doesn't call `next`, then the event processing stop executing after the current middleware completes. +To invoke the next middleware in the queue, use the `next` function. You must call `next.run(payload)` to continue the middleware chain. + If a middleware doesn't call `next`, then the event processing stop executing after the current middleware completes. Middleware is added to Amplitude via `client.addEventMiddleware`. You can add as many middleware as you like. Each middleware runs in the order in which it was added. From b079bd1901bdffc081ce122d4c8ec0da23671213 Mon Sep 17 00:00:00 2001 From: caseyamp Date: Tue, 22 Mar 2022 15:07:14 -0700 Subject: [PATCH 3/3] minor language changes, added description --- docs/analytics/sdks/java-sdk.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/analytics/sdks/java-sdk.md b/docs/analytics/sdks/java-sdk.md index e289fb2b5..9615c8678 100644 --- a/docs/analytics/sdks/java-sdk.md +++ b/docs/analytics/sdks/java-sdk.md @@ -1,13 +1,12 @@ --- title: Java SDK -description: +description: The Amplitude Analytics Java SDK installation and quick start guide. icon: fontawesome/brands/java --- -The backend Java SDK (separate from Android) +This is the documentation for the Amplitude Analytics Java SDK. Note that this is not the Android SDK. ???info "SDK Resources" - - [Java SDK Reference :material-book:](http://amplitude.github.io/Amplitude-Android/) - [Java SDK Repository :material-github:](https://github.com/amplitude/Amplitude-Java) - [Java SDK Releases :material-code-tags-check:](https://github.com/amplitude/Amplitude-Java/releases)