{"id":30312737,"url":"https://github.com/mparticle/mparticle-java-events-sdk","last_synced_at":"2026-01-20T17:05:20.796Z","repository":{"id":43318101,"uuid":"203871013","full_name":"mParticle/mparticle-java-events-sdk","owner":"mParticle","description":"SDK for mParticle's Server Events API","archived":false,"fork":false,"pushed_at":"2024-10-23T21:27:16.000Z","size":272,"stargazers_count":0,"open_issues_count":0,"forks_count":7,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-24T09:49:31.301Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.mparticle.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mParticle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-22T20:48:08.000Z","updated_at":"2024-10-23T21:27:19.000Z","dependencies_parsed_at":"2024-10-24T00:48:41.646Z","dependency_job_id":"614995cc-a034-45d2-8ca2-ef6a6b262f6a","html_url":"https://github.com/mParticle/mparticle-java-events-sdk","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/mParticle/mparticle-java-events-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-java-events-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-java-events-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-java-events-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-java-events-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mParticle","download_url":"https://codeload.github.com/mParticle/mparticle-java-events-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mParticle%2Fmparticle-java-events-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270877423,"owners_count":24661139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-17T17:14:25.786Z","updated_at":"2026-01-20T17:05:15.752Z","avatar_url":"https://github.com/mParticle.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://static.mparticle.com/sdk/mp_logo_black.svg\" width=\"280\"\u003e\n\n## Java Server Events SDK\n\n[![Maven Central Status](https://maven-badges.herokuapp.com/maven-central/com.mparticle/server-events-sdk/badge.svg?style=flat-square)](https://search.maven.org/#search%7Cga%7C1%7Cmparticle)\n\nThis is the mParticle Java SDK for the server-based Events API - use it to send your data to the [mParticle platform](https://www.mparticle.com/) and off to 250+ integrations! The SDK is designed to be use in a variety of environments. It provides a [Retrofit](https://square.github.io/retrofit/) interface as well as serializable models if you prefer to handle HTTP transport on your own.\n\n\u003e This SDK is designed only to be used in a server-side environment. If you're looking for our Android SDK - [please see here](https://github.com/mparticle/mparticle-android-sdk).\n\n\n### Requirements.\n\nJava 1.7 and later.\n\n## Getting Started \n\n### Add the Dependency\n\nThe SDK is available via Maven Central.\n\n#### Gradle\n\n```groovy\nimplementation 'com.mparticle:server-events-sdk:2.6.0'\n```\n\n#### Maven\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.mparticle\u003c/groupId\u003e\n  \u003cartifactId\u003eserver-events-sdk\u003c/artifactId\u003e\n  \u003cversion\u003e2.6.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n#### Local Maven\n\nYou can also install it locally and use it from a local Maven repository:\n\n```sh\n./gradlew uploadArchives\n```\n\n## Create a `Batch`\n\nAll data that passes through mParticle does so in the form of a \"batch.\" A batch describes identities, attributes, events, and other information related to a *single user*. This SDK lets you upload either single batches or multiple batches at a time.\n\nThe full schema of a batch is documented in the [mParticle Events API overview](https://docs.mparticle.com/developers/server/http/). The models in this SDK directly match the JSON referenced in the overview.\n\n```java\nBatch batch = new Batch();\nbatch.environment(Batch.Environment.DEVELOPMENT);\n\n// Set a Data Plan\nContext context = new Context();\nDataPlanContext dpContext = new DataPlanContext();\ndpContext.planId(\"mobile_data_plan\");\ndpContext.planVersion(2);\ncontext.dataPlan(dpContext);\nbatch.context(context);\n\n// Set user identities\nbatch.userIdentities(\n        new UserIdentities()\n                .customerId(\"1234\")\n                .email(\"example@foo.com\")\n);\n\n// Set device identities\nbatch.deviceInfo(\n        new DeviceInformation()\n                .iosAdvertisingId(\"5864e6b0-0d46-4667-a463-21d9493b6c10\")\n);\n\n// Set user attributes\nMap\u003cString, Object\u003e userAttributes = new HashMap\u003c\u003e();\nuserAttributes.put(\"foo\", \"bar\");\nuserAttributes.put(\"foo-array\", new String[]{\"bar1\", \"bar2\"});\nuserAttributes.put(\"foo-array-2\", Arrays.asList(\"bar3\",\"bar4\"));\nbatch.userAttributes(userAttributes);\n\n```\n\n\u003e It's critical to include either user or device identities with your server-side data\n\n## Create Events\n\nAll mParticle events have a similar structure:\n\n- `event_type`: this is the type of event, such as `custom_event` and `commerce_event`\n- `data`: this contains common properties of all events, as well as properties specific to each `event_type`\n\nThe following are common properties that all events share, as represented by the `CommonEventData` class:\n\n```javascript\n{\n\t\"data\" :\n\t{\n\t\t\"event_id\" : 6004677780660780000,\n\t\t\"source_message_id\" : \"e8335d31-2031-4bff-afec-17ffc1784697\",\n\t\t\"session_id\" : 4957918240501247982,\n\t\t\"session_uuid\" : \"91b86d0c-86cb-4124-a8b2-edee107de454\",\n\t\t\"timestamp_unixtime_ms\" : 1402521613976,\n\t\t\"location\" : {},\n\t\t\"device_current_state\" : {},\n\t\t\"custom_attributes\": {},\n\t\t\"custom_flags\": {}\n\t},\n\t\"event_type\" : \"custom_event\"\n}\n\n```\n\nThe Java Server Events SDK represents this structure via an event and an event-data class for each unique event type. For example, `CustomEvent` which can be populated by a `CustomEventData` instance.\n\n### Custom Events\n\n```java\nMap customAttributes = new HashMap\u003c\u003e();\ncustomAttributes.put(\"foo\", \"bar\");\nCustomEvent event = new CustomEvent().data(\n        new CustomEventData()\n                .eventName(\"My Custom Event Name\")\n                .customEventType(CustomEventData.CustomEventType.LOCATION)\n);\nevent.getData().customAttributes(customAttributes);\n```\n\n### Screen Events\n\n```java\nScreenViewEvent event = new ScreenViewEvent().data(\n        new ScreenViewEventData()\n                .screenName(\"foo screen\")\n);\n```\n\n### Commerce Events\n\n```java\nProduct product = new Product()\n    .totalProductAmount(new BigDecimal(\"123.12\"))\n    .id(\"product-id\")\n    .name(\"product-name\");\nProductAction action = new ProductAction()\n    .action(ProductAction.Action.PURCHASE)\n    .totalAmount(new BigDecimal(\"123.12\"))\n    .transactionId(\"foo-transaction-id\")\n    .products(Arrays.asList(product));\nCommerceEvent event = new CommerceEvent().data(\n        new CommerceEventData().productAction(action)\n);\n```\n\n\n## Full Upload Example\n\n### Create an `EventsApi` instance\n\n`EventsApi` is a Retrofit-compatible interface, allowing you to use the rich feature-set of the Retrofit and OkHttp libraries, such as queueing and asynchronous requests.\n\nCreate an API instance with your mParticle workspace credentials. These credentials may be either \"platform\" (iOS, Android, etc) or \"custom feed\" keys:\n\n```java\nEventsApi api = new ApiClient(\"API KEY\", \"API-SECRET\")\n                .createService(EventsApi.class);\n```\n\nBy default, the Java SDK will upload to the US1 Data Center URL.  If the API key you're sending to exists in an mParticle Data Center that's not US1, you can find the right URL for your hosting location on the [mParticle docs site](https://docs.mparticle.com/developers/data-localization/#events-api).  You can then override the base url using the following configuration:\n\n```java\nRetrofit.Builder mybuilder = new Retrofit.Builder().baseUrl(\"https://s2s.eu1.mparticle.com/v2/\").build();\nEventsApi api = new ApiClient(\"API KEY\", \"API-SECRET\")\n                .setAdapterBuilder(mybuilder)\n                .createService(EventsApi.class);\n```\n\n\u003e The mParticle Events API leverages HTTP basic authentication over TLS. \n\n### Perform a Synchronous Upload\n\nThe SDK supports both multi-batch (\"bulk\") or single-batch uploads:\n\n```java\n//assemble your Batch\nBatch batch = new Batch();\n\nbatch.environment(Batch.Environment.DEVELOPMENT);\nbatch.userIdentities(new UserIdentities()\n        .customerId(\"1234\")\n        .email(\"example@foo.com\")\n);\n\n// Add your events\nMap customAttributes = new HashMap\u003c\u003e();\ncustomAttributes.put(\"foo\", \"bar\");\nCustomEvent customEvent = new CustomEvent().data(\n        new CustomEventData()\n                .eventName(\"foo event\")\n                .customEventType(CustomEventData.CustomEventType.LOCATION)\n);\ncustomEvent.getData().customAttributes(customAttributes);\nbatch.addEventsItem(customEvent);\n\nScreenViewEvent screenEvent = new ScreenViewEvent().data(\n        new ScreenViewEventData()\n                .screenName(\"foo screen\")\n);\nbatch.addEventsItem(screenEvent);\n\nEventsApi api = new ApiClient(\"API KEY\", \"API-SECRET\").createService(EventsApi.class);\n\n// Perform a bulk upload\nList\u003cBatch\u003e bulk = new ArrayList\u003c\u003e();\nbulk.add(batch);\nCall\u003cVoid\u003e bulkResult = api.bulkUploadEvents(bulk);\nResponse\u003cVoid\u003e bulkResponse = bulkResult.execute();\n\n// Perform a single upload\nCall\u003cVoid\u003e singleResult = api.uploadEvents(batch);\nResponse\u003cVoid\u003e singleResponse = singleResult.execute();\n```\n\n### Logging\n\nBy default, logging is ignored.  Please implement your own LogHandler to handle log statements.\n\n```java\nLogger.setLogHandler(new DefaultLogHandler());\nLogger.debug(\"Statement\");\n```\n\n### License\n\n[Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmparticle%2Fmparticle-java-events-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmparticle%2Fmparticle-java-events-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmparticle%2Fmparticle-java-events-sdk/lists"}