PubNub Kotlin SDK 7.5.0

This page outlines the steps to follow to create a simple Hello, World application with PubNub. This covers the basics of integrating PubNub in your application: setting up a connection to PubNub, and sending and receiving messages.

PubNub account​

Sign in or create an account to create an app on the Admin Portal and get the keys to use in your application.

When you create a new app, the first set of keys is generated automatically, but a single app can have as many keysets as you like. We recommend that you create separate keysets for production and test environments.

Download the SDK​

OkHttp supported version

This SDK uses the OkHttp library version 3.14.9 and resolves the dependency automatically. If you explicitly use a 4.X.X version of OkHttp in your project, this SDK might not work correctly.

Download the SDK from any of the following sources:

Use Maven​

To integrate PubNub into your project using Maven, add the following dependency in your pom.xml:

<dependency>
  <groupId>com.pubnub</groupId>
  <artifactId>pubnub-gson</artifactId>
  <version>7.5.0</version>
</dependency>

Use Gradle​

To integrate PubNub into your project using Gradle (including Android Studio), add the following dependency in your build.gradle file:

implementation 'com.pubnub:pubnub-kotlin:7.5.0'

Use a .jar file​

To use Pubnub, simply copy the Pubnub-7.5.0 .jar file into your project's libs directory.

https://github.com/pubnub/kotlin/releases/tag/7.5.0

Get the source code​

https://github.com/pubnub/kotlin/

Configure ProGuard​

If you're using ProGuard, configure it as follows.

# Add project specific ProGuard rules here.
# You can control the set of applied configuration files using the
# proguardFiles setting in build.gradle.
#
# For more details, see
#   http://developer.android.com/guide/developing/tools/proguard.html

# If your project uses WebView with JS, uncomment the following
# and specify the fully qualified class name to the JavaScript interface
# class:
#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
#   public *;
#}

# Uncomment this to preserve the line number information for
show all 65 lines

Configure PubNub​

In the IDE of your choice, create a new Kotlin project. In that project, create a new App class with the following content. This is the minimum configuration you need to send and receive messages with PubNub.

Make sure to replace myPubKey and mySubKey with your app's publish and subscribe keys from the Admin Portal.

val config = PNConfiguration(UserId("myUserId")).apply {
    subscribeKey = "mySubKey"
    publishKey = "myPubKey"
}

For more information, refer to the Configuration section of the SDK documentation.

Add event listeners​

Listeners help your app react to events and messages. You can implement custom app logic to respond to each type of message or event.

In addition to setting up listeners, the following code prints out the content of every received message.

pubnub.addListener(object : SubscribeCallback() {

    override fun status(pubnub: PubNub, status: PNStatus) {
        println("Status category: ${status.category}")
        // PNConnectedCategory, PNReconnectedCategory, PNDisconnectedCategory

        println("Status operation: ${status.operation}")
        // PNSubscribeOperation, PNHeartbeatOperation

        println("Status error: ${status.error}")
        // true or false
    }

    override fun presence(pubnub: PubNub, pnPresenceEventResult: PNPresenceEventResult) {
        println("Presence event: ${pnPresenceEventResult.event}")
show all 28 lines

For more information, refer to the Listeners section of the SDK documentation.

Publish and subscribe​

To receive messages sent to a particular channel, you subscribe to it. When you publish a message to a channel, PubNub delivers that message to everyone subscribed to that channel.

The publish() method uses the channel and message variables that you can see in the following code.

To subscribe, you send a subscribe() call. It is best to define the channel and the message before you introduce the listeners and send the subscribe call, so make sure to place the relevant code in the appropriate places within your code.

pubnub.publish(channel = "my_channel", message = "Hello, world")
    .async { result, status ->
    // the result is always of a nullable type
    // it's null if there were errors (status.error)
    // otherwise it's usable

    // handle publish result
    if (!status.error) {
        println("Message timetoken: ${result!!.timetoken}")
    } else {
        // handle error
        status.exception.printStackTrace()
    }
}

show all 16 lines

For more information, refer to the Publish and Subscribe section of the SDK documentation, and to Publishing a Message.

Putting it all together​

Your main() function should now look similar to the following:

import com.google.gson.JsonObject

import com.pubnub.api.PNConfiguration
import com.pubnub.api.PubNub
import com.pubnub.api.callbacks.SubscribeCallback
import com.pubnub.api.enums.PNStatusCategory
import com.pubnub.api.models.consumer.PNStatus
import com.pubnub.api.models.consumer.pubsub.PNMessageResult
import com.pubnub.api.models.consumer.pubsub.PNPresenceEventResult

fun main() {
    val config = PNConfiguration(UserId("myUserId")).apply {
    subscribeKey = "mySubKey"
    publishKey = "myPubKey"

show all 71 lines

Now, run your app to see if you did everything correctly.

Save the App class and run it with gradle run in the terminal. You can use the one that is built in your IDE or the one that your operating system provides. You should see output similar to the following:

Message to send: {"msg":"Hello, world"}
Received message: {"msg":"Hello, world"}
The content of the message is: Hello, world

Congratulations! You've just subscribed to a channel and sent your first message.

Walkthrough​

Instead of focusing on the order in which you wrote the code, let's focus on the order in which it runs. The app you just created does a few things:

  • configures a PubNub connection
  • adds the status, message, and presence event listeners
  • subscribes to a channel
  • publishes a message

Configuring PubNub​

The following code is the minimum configuration you need to send and receive messages with PubNub. For more information, refer to the PNConfiguration section of the SDK documentation.

val config = PNConfiguration(UserId("myUserId")).apply {
subscribeKey = "mySubKey"
publishKey = "myPubKey"

val pubnub = PubNub(config)

Adding event listeners​

Listeners help your app react to events and messages. You can implement custom app logic to respond to each type of message or event.

You added three listeners to the app: status, message, and presence. Status listens for status events and when it receives an event of type PNConnectedCategory, it publishes the message.Message listens for incoming messages on a particular channel. When it receives a message, the app simply prints the received message. This is why you see "Hello, World" displayed in the console. The presence listener reacts to events connected to presence. In this example, the presence listener is a no-operation.

pubnub.addListener(new SubscribeCallback() {

    @Override
    public void status(PubNub pubnub, PNStatus status) {
        if (status.getCategory() == PNStatusCategory.PNUnexpectedDisconnectCategory) {
            // This event happens when radio / connectivity is lost.
        } else if (status.getCategory() == PNStatusCategory.PNConnectedCategory) {
            // Connect event. You can do stuff like publish, and know you'll get it.
            // Or just use the connected event to confirm you are subscribed for
            // UI / internal notifications, etc.
            if (status.getCategory() == PNStatusCategory.PNConnectedCategory) {
                pubnub.publish()
                    .channel(channelName)
                    .message(messageJsonObject)
                    .async((result, publishStatus) -> {
show all 66 lines

For more information, refer to the Listeners section of the SDK documentation.

Publishing and subscribing​

PubNub uses the Publish/Subscribe model for real-time communication. This model involves two essential parts:

  • Channels are transient paths over which your data is transmitted
  • Messages contain the data you want to transmit to one or more recipients

When you want to receive messages sent to a particular channel, you subscribe to it. When you publish a message to a channel, PubNub delivers that message to everyone who is subscribed to that channel. In this example, you subscribe to a channel named myChannel.

A message can be any type of JSON-serializable data (such as objects, arrays, integers, strings) that is smaller than 32 KiB. PubNub will, in most cases, deliver your message to its intended recipients in fewer than 100 ms regardless of their location. You can also share files up to 5MB.

pubnub.publish(
    channel = myChannel,
    message = myMessage
).async { result, status ->
    println(status)
    if (!status.error) {
        println("Message sent, timetoken: ${result!!.timetoken}")
    } else {
        println("Error while publishing")
        status.exception?.printStackTrace()
    }
}

You can subscribe to more than one channel with a single subscribe call but in this example, you subscribe to a single channel:

pubnub.subscribe(
    channels = listOf(myChannel)
)

For more information, refer to the Publish and Subscribe section of the SDK documentation, and to Publishing a Message.

Next steps​

You have just learned how to use the Kotlin SDK to send and receive messages using PubNub. Next, take a look at the SDK's reference documentation which covers PubNub API in more detail.

Last updated on
Related Resources
On this page