Nakama Java

Android optimized Java client for Nakama server.

Nakama is an open-source server designed to power modern games and apps. Features include user accounts, chat, social, matchmaker, realtime multiplayer, and much more.

This client implements the full API and socket options with the server. It's written in C# with minimal dependencies to support Unity, Xamarin, Godot, XNA, and other engines and frameworks.

Full documentation is online - https://heroiclabs.com/docs

Getting Started

You'll need to setup the server and database before you can connect with the client. The simplest way is to use Docker but have a look at the server documentation for other options.

1. Install and run the servers. Follow these instructions.

2. The Java SDK can be imported with either Grade or Maven through Jitpack.

Gradle

repositories {
    maven {
        url 'https://jitpack.io'
    }
}

dependencies {
    implementation 'com.github.heroiclabs.nakama-java:nakama-java:<commit>'
    implementation 'com.github.heroiclabs.nakama-java:satori-java:<commit>'


 // or, depend on the fat Jar which bundles all of the Nakama Java dependencies into a single Jar.
 // implementation 'com.github.heroiclabs.nakama-java:nakama-java-all:<commit>'
 // implementation 'com.github.heroiclabs.nakama-java:satori-java-all:<commit>'
}

Maven

  <repositories>
    <repository>
      <id>jitpack.io</id>
      <url>https://jitpack.io</url>
    </repository>
  </repositories>

  ...
  <dependencies>
    <dependency>
      <groupId>com.github.heroiclabs.nakama-java</groupId>
      <artifactId>nakama-java</artifactId>
      <version>_commit_</version>
      <type>jar</type>
    </dependency>
  </dependencies>

Or, if you would like to depend on a fat JAR with Maven:

  <dependencies>
    <dependency>
      <groupId>com.github.heroiclabs.nakama-java</groupId>
      <artifactId>nakama-java-all</artifactId>
      <version>_commit_</version>
      <type>jar</type>
    </dependency>
  </dependencies>

Alternatively, you can download the client from the releases page and import it into your project. You can also build from source.

You can view full integration examples in the examples folder.

3. Use the connection credentials to build a client object.

import com.heroiclabs.nakama.Client;

public class NakamaSessionManager {
  private final Client client;

  public NakamaSessionManager() {
    client = new DefaultClient("defaultkey", "127.0.0.1", 7349, false);
  }
}

Usage

The client object has many methods to execute various features in the server or open realtime socket connections with the server.

Authenticate

There's a variety of ways to authenticate with the server. Authentication can create a user if they don't already exist with those credentials. It's also easy to authenticate with a social profile from Google Play Games, Facebook, Game Center, etc.

String email = "super@heroes.com";
String password = "batsignal";
Session session = client.authenticateEmail(email, password).get();
System.out.println(session);

Sessions

When authenticated the server responds with an auth token (JWT) which contains useful properties and gets deserialized into a Session object.

System.out.println(session.getAuthToken()); // raw JWT token
System.out.println(session.getUserId());
System.out.println(session.getUsername());
System.out.println("Session has expired: " + session.isExpired());
System.out.println("Session expires at: " + session.getExpireTime());

It is recommended to store the auth token from the session and check at startup if it has expired. If the token has expired you must reauthenticate. The expiry time of the token can be changed as a setting in the server.

String authtoken = "restored from somewhere";
Session session = DefaultSession.restore(authtoken);
if (session.isExpired()) {
    System.out.println("Session has expired. Must reauthenticate!");
}

Requests

The client includes lots of builtin APIs for various features of the game server. These can be accessed with the async methods. It can also call custom logic as RPC functions on the server. These can also be executed with a socket object.

All requests are sent with a session object which authorizes the client.

Account account = client.getAccount(session);
System.out.println(account.getUser().getId());
System.out.println(account.getUser().getUsername());
System.out.println(account.getWallet());

Socket

The client can create one or more sockets with the server. Each socket can have it's own event listeners registered for responses received from the server.

String host = "localhost";
int port = 7350; // different port to the main API port
boolean ssl = false;
SocketClient socket = client.createSocket(host, port, ssl);
ClientListener listener = new AbstractClientListener() {
  @Override
  public void onDisconnect(final Throwable t) {
      System.out.println("Socket disconnected");
  }
};
socket.connect(session, listener).get();
System.out.println("Socket connected successfully.");

By default, all socket messages are processed in a single thread. Advanced users who want to pass a multithreaded ExecutorService to the client.createSocket method should be aware that incoming messages will not necessarily be processed in order by that socket.

Satori

Satori is a liveops server for games that powers actionable analytics, A/B testing and remote configuration. Use the Satori Java Client to communicate with Satori from your Java game or server.

Full documentation is online - https://heroiclabs.com/docs/satori/client-libraries/java/index.html

Getting Started

Create a client object that accepts the API you were given as a Satori customer.

import com.heroiclabs.satori;

Client client = new DefaultClient("https", "your.host.here", 443, "yourApiKey");

Alternatively, for HTTP support rather than gRPC you can create an HttpClient with the same parameters.

Then authenticate with the server to obtain your session.

// Authenticate with the Satori server.
Map<string, string> defaultProperties = new HashMap<string, string>();
Map<string, string> customProperties = new HashMap<string, string>();

session = client.authenticate("identityId", defaultProperties, customProperties);

Using the client you can get any experiments or feature flags, the user belongs to.

ExperimentList experiments = client.getExperiments(session).get();
Flag flag = client.getFlag(session, "FlagName").get();

You can also send arbitrary events to the server:

Map<string, string> metadata = new HashMap<string, string>();
client.Event(session, new Event("gameLaunched", Instant.now(), "my value", metadata);

This is only a subset of the Satori client API, so please see the documentation link listed earlier for the full API.

For Android

Android uses a permissions system which determines which platform services the application will request to use and ask permission for from the user. The client uses the network to communicate with the server so you must add the "INTERNET" permission.

<uses-permission android:name="android.permission.INTERNET"/>

Contribute

To build the codebase you will need to install these dependencies:

• Java Runtime Environment 1.8 through 1.11
• Java Development Kit 1.8 through 1.11
• Buf build tools for protobuf.

For local development on Apple Mac M chipset, you'll need to install:

brew install --cask adoptopenjdk8

Then run the script to download Nakama and Satori protobuf files: ./download-protos.sh <TOKEN>

Then run buf dep update, followed by buf generate to download the dependencies for our protos as well as compiling the protos to Java.

Then run ./gradlew nakamaJar or ./gradlew satoriJar and Gradle will install your dependencies over the network for you prior to building. It will then build the .jar files.

To run tests for Nakama, run ./gradlew nakamaTest -i. To run tests for Satori, run ./gradlew satoriTest -i.

To test a specific test, run ./gradlew nakamaTest --tests <ClassName.methodName> -i

You can also run ./gradlew tasks for a list of available build tasks.

To create a fat JAR with self-contained dependencies, run:

./gradlew nakamaShadowJar or ./gradlew satoriShadowJar.

All JAR artifacts are output to build/libs. The fat JAR will have an -all suffix.

If you'd like to test a Jitpack publish task locally prior to pushing, run:

./gradlew publishToMavenLocal

Jitpack

Jitpack makes builds of each commit on its own servers. You can view the results of each build and the corresponding artifacts at the following url:

https://jitpack.io/com/github/heroiclabs/nakama-java/<commit>/build.log

Generate Docs

API docs are generated with javadoc and deployed to GitHub pages.

When changing the API comments, rerun javadoc and commit the changes in docs/*.

To run javadoc:

./gradlew javadoc

License

This project is licensed under the Apache-2 License.