Android optimized Java client for Nakama server.
Branch: master
Clone or download

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 -

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. Download the client from the releases page and import it into your project. You can also build from source. Alternatively, if you use a build tool like Gradle you can skip the download and fetch it from the central repository.

repositories {
    maven {
        url ''

dependencies {
  compile(group: 'com.heroiclabs.nakama', name: 'client', version: '+')
  compile('org.slf4j:slf4j-api:1.7.25') {
    force = true // don't upgrade to "1.8.0-alpha2"
  1. 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", "", 7349, false);


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


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 = "";
String password = "batsignal";
Session session = client.authenticateEmail(email, password).get();


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 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!");


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);


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() {
  public void onDisconnect(final Throwable t) {
      System.out.println("Socket disconnected");
socket.connect(session, listener).get();
System.out.println("Socket connected successfully.");

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"/>


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

The Gradle project is setup to download and manage the Google Protocol buffers compiler toolchain automatically and generate Protobuf Lite definitions required by the source code.

$> gradle build

Run "gradle tasks" for a list of available build tasks.


This project is licensed under the Apache-2 License.