--- source_url: https://www.pubnub.com/docs/sdks/android/api-reference/configuration title: Configuration API for Android SDK updated_at: 2026-06-23T11:43:37.245Z --- > Documentation Index > For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt > For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt # Configuration API for Android SDK :::warning Unsupported docs PubNub no longer maintains Android SDK docs, but our [Java SDK](https://www.pubnub.com/docs/sdks/java) or [Kotlin SDK](https://www.pubnub.com/docs/sdks/kotlin) are fully compatible with the Android platform and you can use them to build mobile apps, ensuring stable software development. ::: Android complete Application Programming Interface (API) reference for building real-time applications on PubNub, including basic usage and sample code. This guide explains how to configure and use the Android Software Development Kit (SDK). ## Configuration The `PNConfiguration` instance stores user-provided information that controls client behavior. It also exposes properties that let you precisely configure the PubNub client. ### Method(s) To create `configuration` instance you can use the following function in the Android SDK: ```java new PNConfiguration(); ``` | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | setSubscribeKey | String | Yes | | `subscribeKey` from the Admin Portal. | | setPublishKey | String | Optional | | `publishKey` from the Admin Portal (only required if publishing). | | setSecretKey | String | Optional | | `secretKey` (only required for access operations, keep away from Android). | | setCipherKey | String | Optional | | If `cipher` is passed, all communications to and from PubNub will be encrypted. | | setUuid | String | Yes | | `UUID` to use. You should set a unique `UUID` to identify the user or the device that connects to PubNub. It's a UTF-8 encoded string of up to 92 alphanumeric characters. If you don't set the `UUID`, you won't be able to connect to PubNub. | | setLogVerbosity | PNLogVerbosity | Optional | `PNLogVerbosity.NONE` | Set `PNLogVerbosity.BODY` to enable debugging. To disable debugging use the option `PNLogVerbosity.NONE` | | setAuthKey | String | Optional | `Not set` | If Access Manager is utilized, client will use this `authKey` in all restricted requests. | | setCacheBusting | Boolean | Optional | | If operating behind a misbehaving proxy, allow the client to shuffle the subdomains. | | setSecure | Boolean | Optional | `true` | When `true` `TLS` is enabled. `TLS` is enabled by default as of Android P; check [this link](https://android-developers.googleblog.com/2018/04/protecting-users-with-tls-by-default-in.html) if you want to use `false` in this setting (Not Recommended). | | setConnectTimeout | Int | Optional | `5` | How long before the client gives up trying to connect with a subscribe call. The value is in seconds. | | setSubscribeTimeout | Int | Optional | `310` | The subscribe request timeout. The value is in seconds. | | setNonSubscribeRequestTimeout | Int | Optional | `10` | For `non subscribe` operations (publish, herenow, etc), how long to wait to connect to PubNub before giving up with a connection timeout error. The value is in seconds. | | setFilterExpression | String | Optional | `Not set` | Feature to subscribe with a custom filter expression. | | setHeartbeatNotificationOptions | PNHeartbeatNotificationOptions | Optional | `PNHeartbeatNotificationOptions.FAILURES` | `Heartbeat` notification options. By default, the SDK alerts on failed heartbeats (equivalent to `PNHeartbeatNotificationOptions.FAILURES`). Other options including all heartbeats (`PNHeartbeatNotificationOptions.ALL`) and no heartbeats (`PNHeartbeatNotificationOptions.NONE`) are supported. | | setOrigin | String | Optional | | Custom `origin` if needed. To request a custom domain, contact support and follow the [request process](https://www.pubnub.com/docs/general/setup/data-security#request-process). | | setReconnectionPolicy | PNReconnectionPolicy | Optional | `PNReconnectionPolicy.NONE` | Set to `PNReconnectionPolicy.LINEAR` for automatic reconnects. Use `PNReconnectionPolicy.NONE` to disable automatic reconnects. Use `PNReconnectionPolicy.EXPONENTIAL` to set exponential retry interval. | | setPresenceTimeout | Int | Optional | `300` | Sets the custom presence server timeout. The value is in seconds, and the minimum value is `20` seconds. | | setPresenceTimeoutWithCustomInterval | Int, | Optional | `300, 0` | Parameters are presence timeout (same as setPresenceTimeout) and custom heartbeat interval at which to ping the server. | | setProxy | Proxy | Optional | | Instruct the SDK to use a `proxy` configuration when communicating with PubNub servers. For more details see this [https://docs.oracle.com/javase/7/docs/api/java/net/Proxy.html](https://docs.oracle.com/javase/7/docs/api/java/net/Proxy.html) | | setMaximumReconnectionRetries | Int | Optional | `-1` | The config sets how many times to retry to reconnect before giving up. | | setProxySelector | ProxySelector | Optional | | Sets Java ProxySelector. For more details refer to [https://docs.oracle.com/javase/7/docs/api/java/net/ProxySelector.html](https://docs.oracle.com/javase/7/docs/api/java/net/ProxySelector.html) | | setProxyAuthenticator | Authenticator | Optional | | Sets Java Authenticator. For more details, refer to [https://docs.oracle.com/javase/7/docs/api/java/net/Authenticator.html](https://docs.oracle.com/javase/7/docs/api/java/net/Authenticator.html) | | setGoogleAppEngineNetworking | Boolean | Optional | | Enable Google App Engine networking. | | setSuppressLeaveEvents | Boolean | Optional | `false` | When `true` the SDK doesn't send out the `leave` requests. | | requestMessageCountThreshold | Int | Optional | `100` | `PNRequestMessageCountExceededCategory` is thrown when the number of messages into the payload is above `requestMessageCountThreshold`. | | setDisableTokenManager | Boolean | Optional | `false` | Disables the TMS (Token Manager System) in a way that it won't authorize requests even if there are applicable tokens. | | useRandomInitializationVector | Boolean | Optional | `true` | When `true` the initialization vector (IV) is random for all requests (not just for file upload). When `false` the IV is hard-coded for all requests except for file upload. | :::warning Disabling random initialization vector Disable random initialization vector (IV) only for backward compatibility (<`5.0.0`) with existing applications. Never disable random IV on new applications. ::: ### Sample code :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); // subscribeKey from Admin Portal pnConfiguration.setSubscribeKey("SubscribeKey"); // required // publishKey from Admin Portal (only required if publishing) pnConfiguration.setPublishKey("PublishKey"); // secretKey (only required for access operations, keep away from Android) pnConfiguration.setSecretKey("SecretKey"); // if cipherKey is passed, all communicatons to/from pubnub will be encrypted pnConfiguration.setCipherKey("cipherKey"); // UUID to be used as a device identifier pnConfiguration.setUuid("myUniqueUUID"); // Enable Debugging pnConfiguration.setLogVerbosity(PNLogVerbosity.BODY); // if Access Manager is utilized, client will use this authKey in all restricted // requests pnConfiguration.setAuthKey("authKey"); // use SSL. pnConfiguration.setSecure(true); // PSV2 feature to subscribe with a custom filter expression pnConfiguration.setFilterExpression("such=wow"); // heartbeat notifications, by default, the SDK will alert on failed heartbeats. // other options such as all heartbeats or no heartbeats are supported. pnConfiguration.setHeartbeatNotificationOptions(PNHeartbeatNotificationOptions.All); pnConfiguration.setPresenceTimeout(120); // the number of messages into the payload pnConfiguration.setRequestMessageCountThreshold(100); ``` ## Initialization Add PubNub to your project using one of the procedures defined under [How to Get It](https://www.pubnub.com/docs/sdks/android) :::note Permissions Put these permission outside the `` tag, preferable before the tag in the `AndroidManifest.xml`. ```java ``` ::: ### Description This function is used for initializing the PubNub Client API context. This function must be called before attempting to utilize any API functionality in order to establish account level credentials such as `publishKey` and `subscribeKey`. ### Method(s) To `Initialize` PubNub you can use the following method(s) in the Android SDK: ```java new PubNub(pnConfiguration); ``` | Parameter | Description | | --- | --- | | `pnConfiguration` *Type: PNConfiguration | Goto [Configuration](#configuration) for more details. | ### Sample code #### Initialize the PubNub client API :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setSubscribeKey("my_subkey"); pnConfiguration.setPublishKey("my_pubkey"); pnConfiguration.setSecure(true); pnConfiguration.setUuid("myUniqueUUID"); PubNub pubnub = new PubNub(pnConfiguration); ``` ### Returns It returns the PubNub instance for invoking PubNub APIs like `publish()`, `subscribe()`, `history()`, `hereNow()`, etc. ### Other examples #### Initialize a non-secure client :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setSubscribeKey("SubscribeKey"); pnConfiguration.setPublishKey("PublishKey"); pnConfiguration.setSecure(false); pnConfiguration.setUuid("myUniqueUUID"); PubNub pubnub = new PubNub(pnConfiguration); ``` #### Initialization for a Read-Only client In the case where a client will only read messages and never publish to a channel, you can simply omit the `publishKey` when initializing the client: :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setSubscribeKey("my_subkey"); PubNub pubnub = new PubNub(pnConfiguration); ``` #### Use a custom UUID Set a custom `UUID` to identify your users. :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setSubscribeKey("mySubscribeKey"); pnConfiguration.setPublishKey("myPublishKey"); pnConfiguration.setUuid("myUniqueUUID"); PubNub pubnub = new PubNub(pnConfiguration); ``` #### Initializing with SSL enabled This examples demonstrates how to enable PubNub Transport Layer Encryption with `SSL`. Just initialize the client with `setSecure` set to `true`. The hard work is done, now the PubNub API takes care of the rest. Just subscribe and publish as usual and you are good to go. :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setSubscribeKey("my_subkey"); pnConfiguration.setPublishKey("my_pubkey"); pnConfiguration.setSecure(true); pnConfiguration.setUuid("myUniqueUUID"); PubNub pubnub = new PubNub(pnConfiguration); ``` #### Initializing with Access Manager :::note Requires Access Manager add-on This method requires that the *Access Manager* add-on is enabled for your key in the [Admin Portal](https://admin.pubnub.com/). Read the [support page](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) on enabling add-on features on your keys. ::: :::note Secure your secretKey Anyone with the `secretKey` can grant and revoke permissions to your app. Never let your `secretKey` be discovered, and to only exchange it / deliver it securely. Only use the `secretKey` on secure server-side platforms. When you init with `secretKey`, 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. ::: For applications that will administer Access Manager permissions, the API is initialized with the `secretKey` as in the following example: :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setSubscribeKey("my_subkey"); pnConfiguration.setPublishKey("my_pubkey"); pnConfiguration.setSecretKey("my_secretkey"); pnConfiguration.setUuid("myUniqueUUID"); pnConfiguration.setSecure(true); PubNub pubnub = new PubNub(pnConfiguration); ``` Now that the pubnub object is instantiated the client will be able to access the Access Manager functions. The pubnub object will use the `secretKey` to sign all Access Manager messages to the PubNub Network. #### How to set proxy :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setSubscribeKey("mySubscribeKey"); pnConfiguration.setPublishKey("myPublishKey"); pnConfiguration.setSecretKey("mySecretKey"); pnConfiguration.setUuid("myUniqueUUID"); Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("http://mydomain.com", 8080)); pnConfiguration.setProxy(proxy); PubNub pubNub = new PubNub(pnConfiguration); ``` ## UUID These functions are used to set/get a user ID on the fly. ### Method(s) To set/get `UUID` you can use the following method(s) in Android SDK: #### Set UUID ```java pnConfiguration.setUuid(String); ``` | Parameter | Description | | --- | --- | | `uuid` *Type: StringDefault: n/a | `UUID` to be used as a device identifier. If you don't set the `UUID`, you won't be able to connect to PubNub. | #### Get UUID ```java pnConfiguration.getUuid(); ``` This method doesn't take any arguments. ### Sample code #### Set UUID :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setUuid("myUniqueUUID"); ``` #### Get UUID ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.getUuid(); ``` ## Authentication key Setter and getter for users auth key. ### Method(s) #### Set auth key ```java pnConfiguration.setAuthKey(String); ``` | Parameter | Description | | --- | --- | | `Auth Key` *Type: String | If Access Manager is utilized, client will use this `authKey` in all restricted requests. | #### Get auth key ```java pnConfiguration.getAuthKey(); ``` This method doesn't take any arguments. ### Sample code #### Set auth key ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setAuthKey("authKey"); ``` #### Get auth key ```java pnConfiguration.getAuthKey(); ``` ### Returns None. ## Filter expression :::note Requires Stream Controller add-on This method requires that the *Stream Controller* add-on is enabled for your key in the [Admin Portal](https://admin.pubnub.com/). Read the [support page](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) on enabling add-on features on your keys. ::: Stream filtering allows a subscriber to apply a filter to only receive messages that satisfy the conditions of the filter. The message filter is set by the subscribing client(s) but it is applied on the server side thus preventing unwanted messages (those that do not meet the conditions of the filter) from reaching the subscriber. To set or get message filters, you can use the following method. To learn more about filtering, refer to the [Publish Messages](https://www.pubnub.com/docs/general/messages/publish) documentation. ### Method(s) #### Set filter expression ```java pnConfiguration.setFilterExpression(String); ``` | Parameter | Description | | --- | --- | | `filterExpression` *Type: String | PSV2 feature to `subscribe` with a custom filter expression | #### Get filter expression ```java pnConfiguration.getFilterExpression(); ``` This method doesn't take any arguments. ### Sample code #### Set filter expression :::note 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. ::: ```java PNConfiguration pnConfiguration = new PNConfiguration(); pnConfiguration.setFilterExpression("such=wow"); ``` #### Get filter expression ```java pnConfiguration.getFilterExpression(); ``` ## Terms in this document * **PubNub** - PubNub is a real-time messaging platform that provides APIs and SDKs for building scalable applications. It handles the complex infrastructure of real-time communication, including: Message delivery and persistence, Presence detection, Access control, Push notifications, File sharing, Serverless processing with Functions and Events & Actions, Analytics and monitoring with BizOps Workspace, AI-powered insights with Illuminate.