Android SDK reference

Reference Android initialization options, methods, models, and notification listeners.

Configuration

Pushctl.initialize(
    context,
    PushctlConfiguration(
        applicationKey = "push_live_your_client_token",
        apiUrl = "https://pushctl.com/api/v1",
        notificationChannelId = "orders",
        notificationChannelName = "Order updates",
        notificationIcon = R.drawable.ic_notification,
    ),
)

Option	Default	Description
applicationKey	Required	Client token for the application
apiUrl	https://pushctl.com/api/v1	Override only for self-hosting or local development
notificationChannelId	pushctl_default	Android notification channel ID
notificationChannelName	Notifications	User-visible channel name
notificationIcon	App icon	Drawable resource for notifications

Methods

Method	Purpose
initialize(context, key, apiUrl)	Initialize with basic options
initialize(context, configuration)	Initialize with channel and icon options
requestPermission(activity)	Request or synchronize notification permission
syncPermission()	Send the current permission state
waitForRegistration(timeoutMillis, callback)	Wait for confirmed registration; defaults to 15 seconds
login(externalUserId, callback)	Associate this installation with a user and report the API result
logout(callback)	Remove its current user association and report the API result
subscriptionState()	Read installation, identity, permission, token, and registration state
addRegistrationListener	Observe confirmed registration and failures
removeRegistrationListener	Stop observing registration changes
addNotificationClickListener	Observe notification opens
addForegroundNotificationListener	Observe a push received while foregrounded
handleNotificationOpen(intent)	Process an open intent in custom integrations

PushctlOperationCallback receives null on success or a Throwable on failure. Login and logout require a confirmed installation and update local identity only after the API accepts the change.

Subscription state

PushctlSubscriptionState contains installationId, externalUserId, permission, pushToken, registrationStatus, and registrationError. Its computed isRegistered property is true only when registrationStatus is REGISTERED.

Registration status can be UNREGISTERED, REGISTERING, REGISTERED, or FAILED. Implement PushctlRegistrationListener to receive onRegistered(state) and onRegistrationFailed(error) callbacks.

Show Notification model

PushctlNotification contains notificationId, deliveryId, optional title, body, imageUrl, and actionUrl, plus data: Map<String, String>.