Utility Methods API for PubNub Kotlin SDK

Breaking changes in v9.0.0

PubNub Kotlin SDK version 9.0.0 unifies the codebases for Kotlin and Java SDKs, introduces a new way of instantiating the PubNub client, and changes asynchronous API callbacks and emitted status events. These changes can impact applications built with previous versions (< 9.0.0 ) of the Kotlin SDK.

For more details about what has changed, refer to Java/Kotlin SDK migration guide.

The methods on this page are utility methods that don't fit into other categories.

Request execution

Most PubNub Kotlin SDK method invocations return an Endpoint object, which allows you to decide whether to perform the operation synchronously or asynchronously.

You must invoke the .sync() or .async() method on the Endpoint to execute the request, or the operation will not be performed.

val channel = pubnub.channel("channelName")

channel.publish("This SDK rules!").async { result ->
    result.onFailure { exception ->
        // Handle error
    }.onSuccess { value ->
        // Handle successful method result
    }
}

Create Push Payload

This method creates the push payload for use in the appropriate endpoint calls.

Method(s)

val pushPayloadHelper = PushPayloadHelper()

val fcmPayload = FCMPayload()
val apnsPayload = APNSPayload()

pushPayloadHelper.fcmPayload = fcmPayload
pushPayloadHelper.apnsPayload = apnsPayload

Parameter	Type	Required	Description
`apnsPayload`	`APNSPayload`	Optional	Set APNS and APNS2 Payload. Associated devices will receive only the data supplied here within the `pn_apns` key.
`fcmPayload`	`FCMPayload`	Optional	Set FCM Payload. Associated devices will receive only the data supplied here within the `pn_gcm` key.
`commonPayload`	`Map<String, Any>`	Optional	Set common Payload. Native PubNub subscribers will receive the data provided here, together with the `pn_apns` and `pn_gcm` objects.
`build`	`Map<String, Any>`	Yes	Builds the payload from the values set using the parameters.

Basic Usage

Create Push Payload

// Create an instance of PushPayloadHelper
val pushPayloadHelper = PushPayloadHelper()

// Setup FCM parameters (FCMPayload)
val fcmPayload = FCMPayload().apply {
    notification = FCMPayload.Notification().apply {
        title = "Notification title"
        body = "Notification body text"
        image = "http://example.com/image.png"
    }
    data = mapOf(
        "city" to "sf",
        "count" to 71,
        "is_private" to true
    )
show all 74 lines

Response

The PushPayloadHelper#build() operation returns a Map<String, Any> which can be passed directly as the message parameter to the pubnub.publish() method.

Encrypt

This function allow to encrypt the data.

Deprecated

The cipherKey parameter in this method is deprecated. We recommend that you configure a seprate instance of the crypto module and use it for partial encryption.

If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Method(s)

To encrypt the data you can use the following method(s) in Kotlin SDK.

pubnub.encrypt(
    inputString: String,
    cipherKey: String
)

Parameter	Type	Required	Description
`inputString`	`String`	Yes	The data to encrypt.
`cipherKey`	`String`	Optional	Cipher key to use for encryption. If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the `cryptoModule` from PubNub config will be used. For more information, refer to Crypto module configuration.

Basic Usage

Encrypt part of message

val aesCbcCryptoModule = CryptoModule.createAesCbcCryptoModule(cipherKey = "myCipherKey01", randomIv = true)
val stringToBeEncrypted = "string to be encrypted"
val encryptedData = aesCbcCryptoModule.encrypt(stringToBeEncrypted.toByteArray())

Returns

It returns the encrypted inputString as a String.

Encrypt File Input Stream

Encrypts input stream with a cipher key.

Deprecated

Method(s)

pubnub.encryptInputStream(inputStream: InputStream, cipherKey: String)

Parameter	Type	Required	Default	Description
`inputStream`	InputStream	Yes		Stream with content to encrypt.
`cipherKey`	String	Optional	`PNConfiguration.getCipherKey()`	If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the `cryptoModule` from PubNub config will be used. For more information, refer to Crypto module configuration.

Basic Usage

val aesCbcCryptoModule = CryptoModule.createAesCbcCryptoModule(cipherKey = "myCipherKey01", randomIv = true)

val encryptedStream = aesCbcCryptoModule.encryptStream(stringToBeEncrypted.byteInputStream())

Returns

InputStream with encrypted data.

Decrypt

This function allow to decrypt the data.

Deprecated

Method(s)

pubnub.decrypt(
    inputString: String,
    cipherKey: String
)

To decrypt the data you can use the following method(s) in Kotlin SDK.

Parameter	Type	Required	Description
`inputString`	`String`	Yes	The data to decrypt.
`cipherKey`	`String`	Optional	Cipher key to use for decryption.

Basic Usage

val aesCbcCryptoModule = CryptoModule.createAesCbcCryptoModule(cipherKey = "myCipherKey01", randomIv = true)
val stringToBeEncrypted = "string to be encrypted"
val encryptedData = aesCbcCryptoModule.encrypt(stringToBeEncrypted.toByteArray())
val decryptedData = aesCbcCryptoModule.decrypt(encryptedData)

Returns

It returns the decrypted inputString as a String.

Decrypt File Input Stream

Method(s)

Decrypts input stream with a cipher key.

Deprecated

pubnub.decryptInputStream(inputStream: InputStream, cipherKey: String)

Parameter	Type	Required	Default	Description
`inputStream`	InputStream	Yes		Stream with content encrypted data.
`cipherKey`	String	Optional	`PNConfiguration.getCipherKey()`	Cipher key to use for encryption. If provided, the legacy encryption with 128-bit cipher key entropy is used. If not provided, the `cryptoModule` from PubNub config will be used. For more information, refer to Crypto module configuration.

Basic Usage

val aesCbcCryptoModule = CryptoModule.createAesCbcCryptoModule(cipherKey = "myCipherKey01", randomIv = true)

val encryptedStream = aesCbcCryptoModule.encryptStream(stringToBeEncrypted.byteInputStream())
val decryptedStream = aesCbcCryptoModule.decryptStream(encryptedStream)

Returns

InputStream with decrypted data.

Destroy

Destroy frees up the threads and allows for clean exit.

Method(s)

destroy()

Basic Usage

pubnub.destroy()

Returns

None

Get Subscribed Channel Groups

Returns all the subscribed channel groups in a List<String>.

Method(s)

To Get Subscribe Channel Groups you can use the following method(s) in the Kotlin SDK:

fun getSubscribedChannelGroups(): List<String>

Basic Usage

val subscribedChannels = pubnub.getSubscribedChannels()

Response

List<String>

["channel1", "channel2"]

Disconnect

Call the disconnect() method to force the SDK to stop all requests to PubNub server when there are active subscribe channels.

Method(s)

To disconnect() the data transmission you can use the following method(s) in Kotlin SDK.

disconnect()

This method doesn't take any arguments.

Basic Usage

pubnub.disconnect()

Reconnect

Call the reconnect() method to force the SDK to try and reach out PubNub.

Method(s)

To reconnect() the data you can use the following method(s) in Kotlin SDK.

reconnect()

This method doesn't take any arguments.

Basic Usage

pubnub.reconnect()

Timetoken to date

The timetokenToInstant() method of the TimetokenUtil class converts a PubNub timetoken (a unique identifier for each message sent and received in a PubNub channel that is a number of 100-nanosecond intervals since January 1, 1970) to an Instant object representing the corresponding date and time.

Use this method when you want to display the timetoken of each message or event in the message history in a human-readable format.

Method signature

TimetokenUtil.timetokenToInstant(timetoken: Long): Instant

Input

Parameter	Type	Required	Default	Description
`timetoken`	`Long`	Yes	n/a	Represents the PubNub timetoken to convert into a human-readable date format.

Output

Type	Description
`Instant`	The human-readable date representation of the timetoken.

Basic usage

Convert a timetoken value of 17276954606232118 to a human-readable date and time format.

val timetoken: Long = 17276954606232118
val instant: Instant = TimetokenUtil.timetokenToInstant(timetoken)
val localDateTimeInUTC = instant.toLocalDateTime(TimeZone.UTC)

println("PubNub timetoken: ${timetoken}")
println("Current date: ${localDateTimeInUTC.date}")
println("Current time: ${localDateTimeInUTC.time}")

The output of the method is as follows:

PubNub timetoken: 17276954606232118
Current time: 11:24:20.623211800
Current date: 2024-09-30

Date to timetoken

The instantToTimetoken() method of the TimetokenUtil class converts the Instant object representing the corresponding date and time into a PubNub timetoken (a unique identifier for each message sent and received in a PubNub channel that is a number of 100-nanosecond intervals since January 1, 1970).

Use this method to represent a specific date and time as a PubNub timetoken value, for example, to retrieve messages from a PubNub channel at a particular date and time.

Method signature

TimetokenUtil.instantToTimetoken(instant: Instant): Long

Input

Parameter	Type	Required	Default	Description
`instant`	`Instant`	Yes	n/a	Represents the date and time to convert into a PubNub timetoken.

Output

Type	Description
`Long`	Converted timetoken value.

Basic usage

Convert a human-readable date and time, September 30, 2024 12:12:24 GMT, to a timetoken.

val localDateTime = LocalDateTime(year = 2024, monthNumber = 9, dayOfMonth = 30, hour = 12, minute = 12, second =  44, nanosecond =  123456789)
val zone = TimeZone.currentSystemDefault()
val instant = localDateTime.toInstant(zone)
val timetoken = TimetokenUtil.instantToTimetoken(instant)

println("Current date: ${localDateTime.date}")
println("Current time: ${localDateTime.time}")
println("PubNub timetoken: ${timetoken}")

Current date: 2024-09-30
Current time: 12:12:44.123456789
PubNub timetoken: 17276911641234567

Unix timestamp to timetoken

The unixToTimetoken() method of the TimetokenUtil class converts a Unix timestamp (a number of seconds since January 1, 1970) to a PubNub timetoken (a unique identifier for each message sent and received in a PubNub channel that is a number of 100-nanosecond intervals since January 1, 1970).

Use this method when you need a timetoken to retrieve historical messages with a specific timestamp range from Message Persistence.

Method signature

This method takes the following parameters:

TimetokenUtil.unixToTimetoken(unixTime: Long): Long 

Input

Parameter	Type	Required	Default	Description
`unixTime`	`Long`	Yes	n/a	Represents the Unix timestamp to convert into a PubNub timetoken.

Output

Type	Description
`Long`	Converted timetoken value.

Basic usage

Convert a Unix timestamp value of 1727866935316 representing 2024-10-02 11:02:15.316 to PubNub timetoken:

val unixTime = 1727866935316
val timetoken: Long = TimetokenUtil.unixToTimetoken(unixTime)
val instant: Instant = TimetokenUtil.timetokenToInstant(timetoken)
val localDateTime = instant.toLocalDateTime(TimeZone.UTC)

println("Current date: ${localDateTime.date}")
println("Current time: ${localDateTime.time}")
println("PubNub timetoken: ${timetoken}")

The output of the method is as follows:

Current date: 2024-10-02
Current time: 11:02:15.316
PubNub timetoken: 17278669353160000

Timetoken to Unix timestamp

The timetokenToUnix() method of the TimetokenUtil class converts a PubNub timetoken (a unique identifier for each message sent and received in a PubNub channel that is a number of 100-nanosecond intervals since January 1, 1970) to a Unix timestamp (a number of seconds since January 1, 1970).

Use this method to convert PubNub timetoken for use in another context or system that requires a Unix timestamp.

Method signature

TimetokenUtil.timetokenToUnix(timetoken: Long): Long 

Input

Parameter	Type	Required	Default	Description
`timetoken`	`Long`	Yes	n/a	Represents the PubNub timetoken to convert into a Unix timestamp.

Output

Type	Description
`Long`	Converted Unix timestamp value.

Basic usage

Convert a PubNub timetoken 17276954606232118 representing 2024-09-30 11:24:20.623211800 to Unix time:

val timetoken = 17276954606232118
val unixTime = TimetokenUtil.timetokenToUnix(timetoken)
val instant = Instant.fromEpochMilliseconds(unixTime)
val localDateTime = instant.toLocalDateTime(TimeZone.UTC)

println("Current date: ${localDateTime.date}")
println("Current time: ${localDateTime.time}")
println("PubNub timetoken: ${timetoken}")

The output of the method is as follows:

Current date: 2024-09-30
Current time: 11:24:20.623
PubNub timetoken: 17276954606232118

Breaking changes in v9.0.0

Request execution

Create Push Payload​

Method(s)​

Basic Usage​

Create Push Payload​

Response​

Encrypt​

Deprecated

Method(s)​

Basic Usage​

Encrypt part of message​

Returns​

Encrypt File Input Stream​

Deprecated

Method(s)​

Basic Usage​

Returns​

Decrypt​

Deprecated

Method(s)​

Basic Usage​

Returns​

Decrypt File Input Stream​

Method(s)​

Deprecated

Basic Usage​

Returns​

Destroy​

Method(s)​

Basic Usage​

Returns​

Get Subscribed Channel Groups​

Method(s)​

Basic Usage​

Response​

Disconnect​

Method(s)​

Basic Usage​

Reconnect​

Method(s)​

Basic Usage​

Timetoken to date​

Method signature​

Input​

Output​

Basic usage​

Date to timetoken​

Method signature​

Input​

Output​

Basic usage​

Unix timestamp to timetoken​

Method signature​

Input​

Output​

Basic usage​

Timetoken to Unix timestamp​

Method signature​

Input​

Output​

Basic usage​

Create Push Payload

Method(s)

Basic Usage

Create Push Payload

Response

Encrypt

Method(s)

Basic Usage

Encrypt part of message

Returns

Encrypt File Input Stream

Method(s)

Basic Usage

Returns

Decrypt

Method(s)

Basic Usage

Returns

Decrypt File Input Stream

Method(s)

Basic Usage

Returns

Destroy

Method(s)

Basic Usage

Returns

Get Subscribed Channel Groups

Method(s)

Basic Usage

Response

Disconnect

Method(s)

Basic Usage

Reconnect

Method(s)

Basic Usage

Timetoken to date

Method signature

Input

Output

Basic usage

Date to timetoken

Method signature

Input

Output

Basic usage

Unix timestamp to timetoken

Method signature

Input

Output

Basic usage

Timetoken to Unix timestamp

Method signature

Input

Output

Basic usage