External data sources

Illuminate works with real-time apps powered by and not powered by PubNub. If you don't use PubNub Pub/Sub API for real-time communication in your app, send your data using the PubNub Fire API for Illuminate to access the data.

If PubNub powers your app, but you have additional data you’d like to use with Illuminate, you can also send that data through the Fire API and then send it back to the external system after being captured, measured, and analyzed by Illuminate.

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 with the data you need in Illuminate using the Fire API. You can do that either using a fire method from a selected SDK or by sending a direct call to the Fire API.

SDK methods

Send a message to a chosen channel using a fire method from a selected SDK.

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

try {
    const result = await pubnub.fire({
        message: "Hello!",
        channel: "my_channel",
        sendByPost: false, // true to send via post
        meta: {
            cool: "meta",
        }, // fire extra meta with the request
    });

    console.log("message published w/ timetoken", response.timetoken);
} catch (status) {
    // handle error
    console.log(status);
}

Swift

pubnub.fire(
  channel: "my-channel",
  message: "Hello!"
) { result in
  switch result {
  case let .success(timetoken):
    print("Message Successfully Published at: \(timetoken)")
  case let .failure(error):
    print("Failed Response: \(error.localizedDescription)")
  }
}

Kotlin

val config = com.pubnub.api.v2.PNConfiguration.builder(UserId("myUserId"), "demo").apply {
    publishKey = "demo"
}

val channel = pubnub.channel("myChannel")

channel.fire("Hello!").async { result ->
    result.onFailure { exception ->
        println("Error while publishing")
        exception.printStackTrace()
    }.onSuccess { value ->
        println("Message sent, timetoken: ${value.timetoken}")
    }
}

Python

envelope = pubnub.fire() \
    .channel('my_channel') \
    .message('Hello!') \
    .use_post(True) \
    .sync()
print('fire timetoken: %d' % envelope.result.timetoken)

C#

string message = "Hello!";

pubnub.Fire()
    .Message(message)
    .Channel(channel)
    .UsePOST(true)
    .Execute(new PNPublishResultExt(
        (result, status) => {
            if (status.Error) {
                // something bad happened.
                Console.WriteLine("error happened while publishing: " + pubnub.JsonPluggableLibrary.SerializeToJsonString(status));
            } else {
                Console.WriteLine("publish worked! timetoken: " + result.Timetoken.ToString());
            }
        }

show all 16 lines

Go

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

REST API call

As an alternative to using a fire method from an SDK, you can send the data to Illuminate by making a direct HTTP GET call to the PubNub's 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 from the Admin Portal.
sub_key	sub-c-50264475-1902-558x-d213-7p19052012n2	Your subscribe key from the Admin Portal.
channel	myChannel	Channel where you want to fire the message.
callback	0	The JSONP callback name to wrap the function in. Use 0 for no callback.
norep	true	No replication. This value should be true because a message sent using Fire API is not replicated.
Message	The original JSON message {"text":"Hello!"} needs to be a URL-encoded JSON %7B%22text%22%3A%22Hello%21%22%7D.	Needs to 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 structure as for the Publish API. If you need guidance, contact support.

Send data back

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

• Use the Illuminate's Webhook action 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’re publishing to in the Illuminate Decision module.