Use external data with Illuminate
This guide shows you how to send data from an external system to PubNub Illuminate using the Fire API.
Before you start
Before starting, confirm you have:
- A PubNub account with at least one app and keyset. If you do not have one, create it in the Admin Portal. The external system needs the publish and subscribe keys from that keyset.
- Access Manager enabled on the keyset. This is recommended for production keysets. With Access Manager on, the external system needs a token that your server granted with
writepermission on the channel. Fire uses the publish endpoint, so it needs the same permission as publishing. To grant a token, see Grant a token. Keep the secret key on your server. A system that sends with a granted token doesn't need it. - A Business Object for the channel you will fire messages to.
For an overview of how external data sources work with Illuminate, see External data sources.
Map and activate the Business Object
Map and activate the Business Object before you send any data. Activation starts data capture, so Illuminate doesn't capture messages you fire before it.
- Map each data field of your Business Object to a JSON path in the payload you will fire. Use the same JSON path structure as for Publish API messages. The payload format is identical.
- Activate the Business Object. For the steps, see Create a Business Object.
If you need help mapping your payload structure, contact support.
Send a fire request
Send data to Illuminate by firing a message to a channel on your keyset. Choose an SDK or make a direct REST call.
Using an SDK
The Fire API is available in most PubNub SDKs. The following examples fire a "Hello!" message to a channel. Replace the channel name and message with your actual payload.
For SDKs not shown here, Asyncio, C#, Cocoa Objective-C, Cocoa Swift, Go, Java, Kotlin, Objective-C, PHP, Python, Ruby, Swift, and Unity follow the same pattern using the SDK's fire method. Detailed initialization instructions are in the Configuration section of each SDK's documentation.
- JavaScript
- Swift
- Kotlin
- Python
- C#
- Go
1try {
2 const result = await pubnub.fire({
3 message: "Hello!",
4 channel: "my_channel",
5 sendByPost: false, // true to send via post
6 meta: {
7 cool: "meta",
8 }, // fire extra meta with the request
9 });
10
11 console.log("message published w/ timetoken", result.timetoken);
12} catch (status) {
13 // handle error
14 console.log(status);
15}
1pubnub.fire(
2 channel: "my-channel",
3 message: "Hello!"
4) { result in
5 switch result {
6 case let .success(timetoken):
7 print("Message Successfully Published at: \(timetoken)")
8 case let .failure(error):
9 print("Failed Response: \(error.localizedDescription)")
10 }
11}
1val config = com.pubnub.api.v2.PNConfiguration.builder(UserId("myUserId"), "demo").apply {
2 publishKey = "demo"
3}
4
5val channel = pubnub.channel("myChannel")
6
7channel.fire("Hello!").async { result ->
8 result.onFailure { exception ->
9 println("Error while publishing")
10 exception.printStackTrace()
11 }.onSuccess { value ->
12 println("Message sent, timetoken: ${value.timetoken}")
13 }
14}
1envelope = pubnub.fire() \
2 .channel('my_channel') \
3 .message('Hello!') \
4 .use_post(True) \
5 .sync()
6print('fire timetoken: %d' % envelope.result.timetoken)
1string message = "Hello!";
2
3pubnub.Fire()
4 .Message(message)
5 .Channel(channel)
6 .UsePOST(true)
7 .Execute(new PNPublishResultExt(
8 (result, status) => {
9 if (status.Error) {
10 // something bad happened.
11 Console.WriteLine("error happened while publishing: " + pubnub.JsonPluggableLibrary.SerializeToJsonString(status));
12 } else {
13 Console.WriteLine("publish worked! timetoken: " + result.Timetoken.ToString());
14 }
15 }
1res, status, err := pn.Fire().
2 Channel("my-channel").
3 Message("Hello!").
4 Execute()
Using the REST API
Send an HTTPS GET request to the Fire API. Put the URL-encoded JSON message at the end of the path:
1curl 'https://ps.pndsn.com/publish/{pub_key}/{sub_key}/0/{channel}/0/%7B%22text%22%3A%22Hello!%22%7D?uuid={user_id}&auth={token}&norep=true&store=0'
| Parameter | Description |
|---|---|
pub_key | Your publish key from the Admin Portal keyset configuration. |
sub_key | Your subscribe key from the Admin Portal keyset configuration. |
channel | The channel to fire the message to. |
0 after the channel | The JSONP callback name. 0 means no callback. |
| Last path segment | The JSON message payload, URL-encoded. |
uuid | The User ID of the sending system. |
auth | An Access Manager token your server granted with write on the channel. Required if Access Manager is enabled, unless the request is signed. |
norep | Set to true for Fire requests. A fired message isn't replicated across points of presence. |
store | Set to 0 so Message Persistence doesn't store the message. |
A server that holds the secret key can sign the request with the signature and timestamp parameters instead of sending a token. See Initialize a server SDK with a secret key.
A successful request returns HTTP 200 with a JSON array. 1 and "Sent" mean PubNub accepted the message, and the last value is its timetoken:
[1, "Sent", "17901748369820336"]
If Access Manager rejects the request, it returns HTTP 403 and names the channel it refused:
{"error": true, "status": 403, "service": "Access Manager", "message": "Forbidden", "payload": {"channels": ["{channel}"]}}
Check that the token is valid, hasn't expired, and grants write on that channel.