Lua API & SDK Docs 3.6.0

Unsupported SDK

PubNub no longer supports this SDK, but you are welcome to contribute.

Get Code: Source

SDK version

Always use the latest SDK version to have access to the newest features and avoid security vulnerabilities, bugs, and performance issues.

https://github.com/pubnub/lua

Depending on the target/platform you're using, you may need some additional setup. Corona and Moai should not need more setup, their environments should provide all we need. All you need is to use the PubNub Lua module in your projects. You can also use the PubNubUtil module, but it's only for convenience.

The pure Lua platform expects de facto standard lua sockets and crypto modules to be installed and uses the dkjson library that is part of the source tree.

Hello World

Including the code

require "pubnub"

Required UUID

Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the UUID, you won't be able to connect to PubNub.

require "pubnub"
require "PubnubUtil" -- has textout()

local pubnub_obj = pubnub.new({
    publish_key = "demo",
    subscribe_key = "demo",
})
channel = "hello_world"
pubnub_obj:subscribe({
    channel = channel,
    callback = function(message)
        textout(message)
    end,
    error = function()
        textout("Oh no!!! Dropped Connection!")

show all 21 lines

Copy and paste examples

In addition to the Hello World sample code, we also provide some copy and paste snippets of common API functions:

Init

Instantiate a new Pubnub instance. Only the subscribe_key is mandatory. Also include publish_key if you intend to publish from this instance, and the secret_key if you wish to perform Access Manager administrative operations from this Lua instance.

Important

It is not a best practice to include the secret key in client-side code for security reasons.

When you init with secret_key, you get root permissions for the Access Manager. With this feature you don't have to grant access to your servers to access channel data. The servers get all access on all channels.

Required UUID

Always set the UUID to uniquely identify the user or device that connects to PubNub. This UUID should be persisted, and should remain unchanged for the lifetime of the user or the device. If you don't set the UUID, you won't be able to connect to PubNub.

Initializing the client

require "pubnub"

local pubnub_obj = pubnub.new({
    publish_key = "demo",
    subscribe_key = "demo",
    ssl = true
})

Time

Call time() to verify the client connectivity to the origin:

pubnub_obj:time(function(t)
    textout("Got timetoken: " .. t)
end)

Subscribe

Subscribe (listen on) a channel:

pubnub_obj:subscribe({
    channel = "demo",
    connect = function()
        textout('Connected to channel ')
        textout(channel)
    end,
    callback = function(message)
        textout(message)
    end,
    error = function()
        textout("Oh no!!! Dropped Connection!")
    end
})

Publish

Publish a message to a channel:

pubnub_obj:publish({
    channel = "demo",
    message = "42",
    error = function(r)
        textout(r)
    end
})

Here Now

Get occupancy of who's here now on the channel by UUID:

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

pubnub_obj:here_now({
    channel = "demo",
    callback = function(response)
        textout(response)
    end,
    error = function (response)
        textout(response)
    end
})

Presence

Subscribe to real-time Presence events, such as join, leave, and timeout, by UUID. Setting the presence attribute to a callback will subscribe to presents events on my_channel:

Requires Presence

This method requires that the Presence add-on is enabled for your key in the Admin Portal.

pubnub_obj:subscribe({
    channel = "demo",
    connect = function()
        textout('Connected to channel ')
        textout(channel)
    end,
    callback = function(message)
        textout(message)
    end,
    presence = function(notification)
        textout(notification)
    end,
    error = function()
        textout("Oh no!!! Dropped Connection!")
    end

show all 16 lines

History

Retrieve published messages from archival storage:

Requires Message Persistence

This method requires that Message Persistence is enabled for your key in the Admin Portal.

pubnub_obj:history({
    channel = "demo",
    count = 50,
    callback = function(response)
        textout(response)
    end,
    error = function (response)
        textout(response)
    end
})

Unsubscribe

Stop subscribing (listening) to a channel:

pubnub_obj:unsubscribe({
    channel = "demo",
})