These docs are for PubNub 4.0 for Python-Tornado V4 which is our latest and greatest! For the docs of the older versions of the SDK, please check PubNub 3.0 for Python, PubNub 3.0 for Python-Tornado and PubNub 3.0 for Python-Twisted.
If you have questions about the PubNub for Python SDK, please contact us at firstname.lastname@example.org.
PubNub is a globally distributed Data Stream Network. We provide many Points of Presence around the planet for client devices to connect locally. This level of connectivity offering is unusual and provides above and beyond the industry standards of resilient operations and performance capabilities.
When a client devices opens a TCP connection to PubNub, that connection policy is unlimited. This means that the connection will remain open forever until the client closes the connection or the server enters a maintenance state. If a client disconnects unintentionally, PubNub remembers the undelivered data for a short duration.
When the client's network has been restored, PubNub will automatically bundle and gzip-compress all the messages into a single payload, allowing the client to
catch-up after being offline.
This doc explains the wrong way and right way to use PubNub. As you read through this document, you will discover the most common mistakes a customer makes with PubNub.
Sending messages on PubNub is easy. Call the PubNub Publish API. This is the starting point of your development adventure.
Client brokers message to Server. This is inefficient. Your client should be using the Publish command to net the full benefits of PubNub. By using PubNub incorrectly the client will have multi-second latencies. The client doesn't have redundancy. Nearby users do not get sub 50ms round-trip performance. This is the inefficient way to use PubNub. Keep reading to gain full performance of PubNub.
The client publishes and subscribes to PubNub directly. The client receives global average latency of 100ms. Nearby users get sub 50ms latency. During connectivity duress, the client will be routed to the next accessible route. The client uses an Auth Key with granted access to Publish on a data channel.
When you need to have your server involved for business logic reasons or data copy reasons. This pattern shows you the best approach for integrating server-side logic with PubNub.
Often you'll find the need to run business logic on your JSON messages, but without slowing the message delivery down. You can do this by creating an onAfter event handler. This handler type will allow you to execute server logic on a copy of your JSON message asynchronously while the original JSON message is on it's way to be delivered to the mobile phone.
You can integrate 3rd party APIs easily. Enable
The payload returned from the API server can be used to augment and modify the original JSON message inline. Or you can save the original message to the 3rd party API using an onAfter event handler.
Server sent events are possible using PubNub. You can notify your users the completion status of a long-running task. Remember that if the event is client initiated, the client must publish directly to PubNub. Sending events from your server should only be for asynchronous tasks like a timer/cron, system level event or long running task status.
You may be considering a proxy in-the-middle solution. However this breaks down quickly when encryption and TCP connection duration policies conflict. Poor performance and the loss of reliability for the mobile app's connectivity.
In order to receive messages using PubNub you must subscribe to a data channel. This is done by calling the subscribe API using the PubNub SDK. When you invoke subscribe, the mobile app will open a TCP connection to the nearest PubNub data center. The connection is left open forever. When the mobile app is closed, the connection is cleared.
You may want to copy messages to your own database for indexing or backup purposes.
Sending data directly to your server from the client is the inefficient way to copy data from PubNub. The optimal way is to publish or fire your message directly to your local PubNub POP. PubNub provides multiple points of presence allowing your client device fast reliable connectivity.
PubNub includes Multi-datacenter Replicated Storage. Your messages are configurable to be indexed and stored across multiple PubNub points of presence. This allows you to fetch the history for a data channel on a periodic interval. You can download every message from your app via the storage and playback paging API. After you've fetched your messages, you can save them to your database and process the messages as you need.
When providing the mobile phone app with API keys (
CipherKey / etc ) you should never hard-code the keys directly in the app. The mobile app should authenticate itself by calling a secure endpoint with access credentials.
After successful authentication, the endpoint will return access tokens for only the necessary data channels. PubNub includes authentication endpoints that you can use in this situation if you don't have your own.
You can program a
PubNub Functions Endpoint to authenticate the user and pass the all the needed access keys including the AuthKey. Your business policies may also require key rotation periods and short session IDs. PubNub includes
In order to authenticate and provide access to
PubNub's network for your users, you need to provide them API keys. The client is able to perform the permitted activities such as Read/Write/Admin/Manage.
The key exchange can occur after authentication. There are many authentication endpoints including your own. PubNub
PubNub Functions Endpoints offers this as well shown in the next example.
When you hard code your API keys for access to PubNub, you'll put yourself in a security risk situation. You will no longer have access to Key Rotation capabilities. There is a way out of this, however it's not pretty. You'll be stuck in a multi-deploy multi-week work cycle in a process called Key Migration.
This is much more involved and it's better to avoid hard coding in general. If you don't have a web server, you can use
PubNub Functions Endpoints to store your access keys. The endpoint is accessible from your client device via HTTP REST. The endpoint when called via HTTP will return access credentials to the client device including a Publish Key, Subscribe Key and an Auth Key generated via PubNub Grant method.
It is not recommended to offer an unlimited TTL when creating an Auth Key for your users. Auth keys should be treated as temporary access tokens, similar to a session ID. There may be debugging/testing purposes where you may want to grant a one-time Unlimited TTL Auth Key. However Unlimited TTLs should not be given to your users.
Never expose your Secret Key to ANYONE. Always keep your keys secret. Ideally you should keep your secrets in an encrypted vault system. Upon CI/CD deployment phase, the keys will be copied securely to your server code. Alternatively the keys vault may have a fetch endpoint which is accessible inside your VPC.