External data sources

Illuminate works with real-time apps that use PubNub and with external systems. Whether or not you use the PubNub Pub/Sub API, you can send data with the PubNub Fire API so Illuminate can access it.

If PubNub powers your app and you have additional data to use with Illuminate, send it through the Fire API. After Illuminate captures, measures, and analyzes the data, you can send results back to your external system.

Send data

To use external data with Illuminate, follow these steps:

1. Create an account in the Admin Portal to manage and configure your PubNub services.
2. Create a new app and, within the app, create a keyset (Publish Key, Subscribe Key, and a Secret Key) — you'll need them to authenticate and secure your application's interactions with PubNub's APIs.
3. Enable Access Manager on your keyset (recommended for production keysets) to control who can publish to the newly-created keyset.
4. Use the created keyset to send a fire request (the Fire API fire method) with the data you need in Illuminate. You can use an SDK method from a selected SDK or make a direct call to the Fire API.

Choose the option that fits your environment: SDK methods for integrated apps or a direct REST call for standalone use.

SDK methods

Send a message to a channel using the SDK’s fire method.

1. Choose a PubNub SDK that supports the Fire API: Asyncio, C#, Cocoa Objective-C, Cocoa Swift, Go, Java, JavaScript , Kotlin, Objective-C, PHP, Python, Ruby, Swift, or Unity.

2. Initialize this SDK using the keyset from the Admin Portal. Detailed instructions are in the Configuration section of each SDK's documentation.

3. Use the fire method of a given SDK (names of these methods can slightly differ depending on the selected SDK) to fire a message on a channel.

   These are some basic examples of firing a "Hello!" message in selected SDKs.

JavaScript

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", response.timetoken);
12} catch (status) {
13    // handle error
14    console.log(status);
15}

Swift

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}

Kotlin

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}

Python

1envelope = pubnub.fire() \
2    .channel('my_channel') \
3    .message('Hello!') \
4    .use_post(True) \
5    .sync()
6print('fire timetoken: %d' % envelope.result.timetoken)

C#

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

show all 16 lines

Go

1res, status, err := pn.Fire().
2            Channel("my-channel").
3            Message("Hello!").
4            Execute()

REST API call

As an alternative to SDK methods, you can send data to Illuminate by making a direct HTTP GET call to the PubNub Fire API.

Check this sample call with these test parameters for reference. By making this call, you will send a "Hello!" message to the specified channel myChannel without replication across point-of-presence (POPs).

Parameter	Value	Description
pub_key	pub-c-50264475-1902-558x-b37b-56d7fb64bf45	Your publish key obtained from the Admin Portal keyset configuration.
sub_key	sub-c-50264475-1902-558x-d213-7p19052012n2	Your subscribe key obtained from the Admin Portal keyset configuration.
channel	myChannel	The channel where you fire the message.
callback	0	The JSONP callback name. Use 0 for no callback.
norep	true	Message is not replicated. Set to true for Fire API requests.
Message	The original JSON message {"text":"Hello!"} must be URL‑encoded: %7B%22text%22%3A%22Hello%21%22%7D.	The message must be URL‑encoded.

A sample HTTP GET call with test parameters:

GET http://ps.pndsn.com/publish/pub-c-50264475-1902-558x-b37b-56d7fb64bf45/sub-c-50264475-1902-558x-d213-7p19052012n2/0/myChannel/0?callback=0&store=0&norep=true&message=%7B%22text%22%3A%22Hello!%22%7D

Alternatively, a sample cURL command with test parameters:

curl -G \
   'https://ps.pndsn.com/publish/pub-c-50264475-1902-558x-b37b-56d7fb64bf45/sub-c-50264475-1902-558x-d213-7p19052012n2/0/myChannel/0/%7B%22text%22%3A%22Hello!%22%7D' \
   --data-urlencode 'norep=true'

Data mapping

To map the data sent through the Fire API so that Illuminate can recognize it, follow the same JSON structure as the Publish API. If you need guidance, contact support.

Send data back

You can send data processed or analyzed by Illuminate back to an external system, application, or service in one of the following ways:

• Use the Webhook action in Illuminate and the keyset on which you fired the data to Illuminate.
• Create a new keyset and use PubNub's Pub/Sub API by subscribing to the channel you publish to in the Illuminate Decision module.