# Class PushClient

java.lang.Object
com.codename1.push.PushClient

public final class PushClient extends Object

Owns push registration and delivers typed push events to an application.

Create exactly one client from the application's `init()` method, keep it in a field on the main application class, and call `register()` from `start()`. Registration is idempotent, so it is safe for `start()` to call it again when Codename One resumes the application. Do not call `unregister()` from `stop()`; unregistering removes the device subscription and is intended for an explicit user opt-out.

The listener is mandatory and is installed before native registration starts. Messages that reach the runtime before `register()` are kept in a bounded process-local queue and replayed when the client becomes active. Native cold-start implementations also persist messages until the Codename One runtime starts. All listener and registration-sink callbacks run on the Codename One EDT.

Codename One does not discover a listener with reflection or `Class.forName()`. Calling `build()` without a listener fails immediately, but the application is responsible for retaining the client and calling `register()`. Only one client can be active in a process.

See Also:
  - `PushListener`
  - `PushTransport`
  - `PushRegistrationSink`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `PushClient.Builder`
  Configures a `PushClient`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static PushClient.Builder`
  `builder(String appId)`
  Starts a client builder for a managed BuildCloud push application.
  `static void`
  `dispatch(String envelopeJson)`
  Delivers an encoded schema-3 envelope from generated native code.
  `static PushCallback`
  `getActiveCallback()`
  Returns the compatibility callback used by generated native bootstraps.
  `String`
  `getAppId()`
  Returns the application key supplied to `builder(String)`.
  `PushSubscription`
  `getSubscription()`
  Returns the latest native subscription reported by the transport.
  `static boolean`
  `hasActiveClient()`
  Indicates whether an active client can receive a native message now.
  `void`
  `register()`
  Activates this client and requests native push registration.
  `void`
  `unregister()`
  Removes this device's subscription.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### builder

    public static PushClient.Builder builder(String appId)

    Starts a client builder for a managed BuildCloud push application.

    The application key is displayed in the Push section of the Codename One Console. It identifies the application during client registration; it is not a server API key. Install a `PushTransport` on the returned builder to bypass BuildCloud and use an application-owned push server.

    Parameters:
      `appId` - the non-empty Push application key, or an application-owned identifier when using a custom transport
    Returns:
      a new builder
    Throws:
      `IllegalArgumentException` - if `appId` is null or empty

  - ### register

    public void register()

    Activates this client and requests native push registration.

    This method is idempotent. Calling it from each invocation of the application's `start()` method requests registration only once. A native token persisted before this client becomes active is replayed immediately, then the platform is asked to refresh it. Registration otherwise completes asynchronously through `PushListener.onRegistration(PushSubscription)` or `PushListener.onError(PushError)`. Messages queued before activation are replayed before this method requests a new native token.

    If another `PushClient` is already active, this client reports an `active_client` error and remains inactive.

  - ### unregister

    public void unregister()

    Removes this device's subscription.

    Use this for an explicit notification opt-out or account-removal workflow, not as part of the normal `stop()` lifecycle. A later call to `register()` may subscribe again after unregistration completes. Custom transports report completion through `PushTransport.Callback.unregistered()`.

  - ### getAppId

    public String getAppId()
    Returns the application key supplied to `builder(String)`.
    Returns:
      the application key

  - ### getSubscription

    public PushSubscription getSubscription()
    Returns the latest native subscription reported by the transport.
    Returns:
      the current subscription, or `null` before registration or after unregistration

  - ### getActiveCallback

    public static PushCallback getActiveCallback()

    Returns the compatibility callback used by generated native bootstraps.

    Application code should use `PushListener`; this method exists for generated platform code and native transport integrations.

    Returns:
      the active native callback, or `null` before a client is registered

  - ### hasActiveClient

    public static boolean hasActiveClient()
    Indicates whether an active client can receive a native message now.
    Returns:
      `true` after `register()` activates a client and before unregistration completes

  - ### dispatch

    public static void dispatch(String envelopeJson)

    Delivers an encoded schema-3 envelope from generated native code.

    If no client is active yet, the message is queued and replayed on the next successful `register()`. Application code normally does not call this method; a custom `PushTransport` should use its callback's `PushTransport.Callback.message(String)` method.

    Parameters:
      `envelopeJson` - the complete schema-3 JSON envelope