Java Client SDK

The OneSignal Java client is a server OneSignal SDK for Java. Integrate OneSignal with your backend events, data, and more.

🚧

Backend SDKs in User Model Beta

You still can try using new User Model endpoints, we advise customers to not use these SDKs in production.

Requirements

Building the API client library requires:

  1. Java 1.8+
  2. Maven (3.8.3+)/Gradle (7.2+)

Installation

To install the API client library to your local Maven repository, simply execute:

mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>org.openapitools</groupId>
  <artifactId>onesignal-java-client</artifactId>
  <version>1.2.1</version>
  <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

  repositories {
    mavenCentral()     // Needed if the 'onesignal-java-client' jar has been published to maven central.
    mavenLocal()       // Needed if the 'onesignal-java-client' jar has been published to the local maven repo.
  }

  dependencies {
     implementation "org.openapitools:onesignal-java-client:1.2.1"
  }

Others

At first generate the JAR by executing:

mvn clean package

Then manually install the following JARs:

  • target/onesignal-java-client-1.2.1.jar
  • target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:


// Import classes:
import com.onesignal.client.ApiClient;
import com.onesignal.client.ApiException;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.*;
import com.onesignal.client.models.*;
import com.onesignal.client.api.DefaultApi;

public class Example {
  private static final String appId = "YOUR_APP_ID";
  private static final String appKeyToken = "YOUR_API_KEY";
  private static final String userKeyToken = "YOUR_USER_TOKEN";

  private static Notification createNotification() {
    Notification notification = new Notification();
    notification.setAppId(appId);
    notification.setIsChrome(true);
    notification.setIsAnyWeb(true);
    notification.setIncludedSegments(Arrays.asList(new String[]{"Subscribed Users"}));
    StringMap contentStringMap = new StringMap();
    contentStringMap.en("Test");
    notification.setContents(contentStringMap);

    return notification;
  }

  public static void main(String[] args) {
    // Setting up the client
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    HttpBearerAuth appKey = (HttpBearerAuth) defaultClient.getAuthentication("app_key");
    appKey.setBearerToken(appKeyToken);
    HttpBearerAuth userKey = (HttpBearerAuth) defaultClient.getAuthentication("user_key");
    userKey.setBearerToken(userKeyToken);
    api = new DefaultApi(defaultClient);

    // Setting up the notification
    Notification notification = createNotification();

    // Sending the request
    CreateNotificationSuccessResponse response = api.createNotification(notification);

    // Checking the result
    System.out.print(response.getId());
  }
}

Documentation for API Endpoints

All URIs are relative to https://onesignal.com/api/v1

ClassMethodHTTP requestDescription
DefaultApibeginLiveActivityPOST /apps/{app_id}/live_activities/{activity_id}/tokenStart Live Activity
DefaultApicancelNotificationDELETE /notifications/{notification_id}Stop a scheduled or currently outgoing notification
DefaultApicreateAppPOST /appsCreate an app
DefaultApicreateNotificationPOST /notificationsCreate notification
DefaultApicreatePlayerPOST /playersAdd a device
DefaultApicreateSegmentsPOST /apps/{app_id}/segmentsCreate Segments
DefaultApicreateSubscriptionPOST /apps/{app_id}/users/by/{alias_label}/{alias_id}/subscriptions
DefaultApicreateUserPOST /apps/{app_id}/users
DefaultApideleteAliasDELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity/{alias_label_to_delete}
DefaultApideletePlayerDELETE /players/{player_id}Delete a user record
DefaultApideleteSegmentsDELETE /apps/{app_id}/segments/{segment_id}Delete Segments
DefaultApideleteSubscriptionDELETE /apps/{app_id}/subscriptions/{subscription_id}
DefaultApideleteUserDELETE /apps/{app_id}/users/by/{alias_label}/{alias_id}
DefaultApiendLiveActivityDELETE /apps/{app_id}/live_activities/{activity_id}/token/{subscription_id}Stop Live Activity
DefaultApiexportPlayersPOST /players/csv_export?app_id={app_id}CSV export
DefaultApifetchAliasesGET /apps/{app_id}/subscriptions/{subscription_id}/user/identity
DefaultApifetchUserGET /apps/{app_id}/users/by/{alias_label}/{alias_id}
DefaultApifetchUserIdentityGET /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
DefaultApigetAppGET /apps/{app_id}View an app
DefaultApigetAppsGET /appsView apps
DefaultApigetEligibleIamsGET /apps/{app_id}/subscriptions/{subscription_id}/iams
DefaultApigetNotificationGET /notifications/{notification_id}View notification
DefaultApigetNotificationHistoryPOST /notifications/{notification_id}/historyNotification History
DefaultApigetNotificationsGET /notificationsView notifications
DefaultApigetOutcomesGET /apps/{app_id}/outcomesView Outcomes
DefaultApigetPlayerGET /players/{player_id}View device
DefaultApigetPlayersGET /playersView devices
DefaultApiidentifyUserByAliasPATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}/identity
DefaultApiidentifyUserBySubscriptionIdPATCH /apps/{app_id}/subscriptions/{subscription_id}/user/identity
DefaultApitransferSubscriptionPATCH /apps/{app_id}/subscriptions/{subscription_id}/owner
DefaultApiupdateAppPUT /apps/{app_id}Update an app
DefaultApiupdateLiveActivityPOST /apps/{app_id}/live_activities/{activity_id}/notificationsUpdate a Live Activity via Push
DefaultApiupdatePlayerPUT /players/{player_id}Edit device
DefaultApiupdatePlayerTagsPUT /apps/{app_id}/users/{external_user_id}Edit tags with external user id
DefaultApiupdateSubscriptionPATCH /apps/{app_id}/subscriptions/{subscription_id}
DefaultApiupdateUserPATCH /apps/{app_id}/users/by/{alias_label}/{alias_id}

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

app_key

  • Type: HTTP basic authentication

user_key

  • Type: HTTP basic authentication

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.