com.wonderpush.sdk

Class WonderPush

java.lang.Object

com.wonderpush.sdk.WonderPush

public class WonderPush
extends java.lang.Object

Main class of the WonderPush SDK.

You would normally only interact with this class, which has all static members.

Make sure you properly installed the WonderPush SDK, as described in the guide.

You must call initialize(Context) before using any other function.

Troubleshooting tip: As the SDK should not interfere with your application other than when a notification is to be shown, make sure to monitor your logs for the WonderPush tag during development, if things did not went as smoothly as they should have.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	INTENT_INTIALIZED Local intent broadcasted when the WonderPush SDK has been initialized and network is reachable.
static java.lang.String	INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_ACTION Intent action for notification button action `method`.
static java.lang.String	INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_AUTHORITY Intent authority for notification button action `method`.
static java.lang.String	INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_ARG Intent query parameter key for the notification button action `method` argument.
static java.lang.String	INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_METHOD Intent query parameter key for the notification button action `method` method name.
static java.lang.String	INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_SCHEME Intent scheme for notification button action `method`.
static java.lang.String	INTENT_NOTIFICATION_OPENED Local intent broadcasted when a push notification created by the WonderPush SDK has been opened.
static java.lang.String	INTENT_NOTIFICATION_OPENED_EXTRA_BUTTON_INDEX The extra key indicating which action button the user clicked on the notification in a INTENT_NOTIFICATION_WILL_OPEN intent.
static java.lang.String	INTENT_NOTIFICATION_OPENED_EXTRA_FROM_USER_INTERACTION The extra key for whether the user clicked the notification or it was automatically opened by the SDK in a INTENT_NOTIFICATION_OPENED intent.
static java.lang.String	INTENT_NOTIFICATION_OPENED_EXTRA_RECEIVED_PUSH_NOTIFICATION The extra key for the original received push notification intent in a INTENT_NOTIFICATION_OPENED intent.
static java.lang.String	INTENT_NOTIFICATION_WILL_OPEN Local intent broadcasted when a push notification created by the WonderPush SDK is to be opened, but no activity is to be started.
static java.lang.String	INTENT_NOTIFICATION_WILL_OPEN_EXTRA_AUTOMATIC_OPEN The extra key denoting whether to automatically display a rich notification message in a INTENT_NOTIFICATION_WILL_OPEN intent.
static java.lang.String	INTENT_NOTIFICATION_WILL_OPEN_EXTRA_FROM_USER_INTERACTION The extra key for whether the user clicked the notification or it was automatically opened by the SDK in a INTENT_NOTIFICATION_WILL_OPEN intent.
static java.lang.String	INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE The extra key denoting the received push notification type, for a INTENT_NOTIFICATION_WILL_OPEN intent.
static java.lang.String	INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE_DATA The value associated to data push notifications (aka silent notifications), corresponding to the extra key INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE.
static java.lang.String	INTENT_NOTIFICATION_WILL_OPEN_EXTRA_RECEIVED_PUSH_NOTIFICATION The extra key for the original received push notification intent in a INTENT_NOTIFICATION_WILL_OPEN intent.
static java.lang.String	INTENT_PUSH_TOKEN_CHANGED Local intent broadcasted when the push token has changed.
static java.lang.String	INTENT_PUSH_TOKEN_CHANGED_EXTRA_OLD_KNOWN_PUSH_TOKEN The extra key for the previously known push token, can be null.
static java.lang.String	INTENT_PUSH_TOKEN_CHANGED_EXTRA_PUSH_TOKEN The extra key for the new push token, can be null.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	getAccessToken() Gets the access token, used to grant access to the current installation to the WonderPush REST API.
static java.lang.String	getDeviceId() Gets the device id, used to identify a single device across applications, and to correctly identify multiple users on a single device.
static org.json.JSONObject	getInstallationCustomProperties() Returns the latest known custom properties attached to the current installation object stored by WonderPush.
static java.lang.String	getInstallationId() Gets the device id, used to identify a single device across applications, and to correctly identify multiple users on a single device.
static boolean	getNotificationEnabled() Returns whether push notification are enabled.
static java.lang.String	getPushToken() Gets the push token, used to send notification to this installation.
static java.lang.String	getUserId() Gets the user id, used to identify a single identity across multiple devices, and to correctly identify multiple users on a single device.
static void	initialize(android.content.Context context) Initialize WonderPush. Call this method before using WonderPush.
static void	initialize(android.content.Context context, java.lang.String clientId, java.lang.String clientSecret) Initialize WonderPush from your WonderPushInitializer implementation.
static boolean	isReady() Whether the SDK is ready to operate and the INTENT_INTIALIZED intent has been dispatched.
static boolean	onBroadcastReceived(android.content.Context context, android.content.Intent intent, int iconResource, java.lang.Class<? extends android.app.Activity> activityClass) Method to be called in your own Google Cloud Messaging BroadcastReceiver to handle WonderPush push notifications.
static void	putInstallationCustomProperties(org.json.JSONObject customProperties) Update the custom properties attached to the current installation object stored by WonderPush.
static void	setLogging(boolean enable) Whether to enable debug logging.
static void	setNotificationEnabled(boolean status) Sets whether to enable push notifications for the current device.
static void	setUserId(java.lang.String userId) Sets the user id, used to identify a single identity across multiple devices, and to correctly identify multiple users on a single device.
static boolean	showPotentialNotification(android.app.Activity activity, android.content.Intent intent) Method to call on your onNewIntent() and onCreate() methods to handle the WonderPush notification.
static void	trackEvent(java.lang.String type) Send an event to be tracked to WonderPush.
static void	trackEvent(java.lang.String type, org.json.JSONObject customData) Send an event to be tracked to WonderPush.

Methods inherited from class java.lang.Object

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

Field Detail

INTENT_INTIALIZED

public static final java.lang.String INTENT_INTIALIZED

Local intent broadcasted when the WonderPush SDK has been initialized and network is reachable.

See Also:

Constant Field Values

INTENT_PUSH_TOKEN_CHANGED

public static final java.lang.String INTENT_PUSH_TOKEN_CHANGED

Local intent broadcasted when the push token has changed.

See Also:

Constant Field Values

INTENT_PUSH_TOKEN_CHANGED_EXTRA_OLD_KNOWN_PUSH_TOKEN

public static final java.lang.String INTENT_PUSH_TOKEN_CHANGED_EXTRA_OLD_KNOWN_PUSH_TOKEN

The extra key for the previously known push token, can be null.

See Also:

Constant Field Values

INTENT_PUSH_TOKEN_CHANGED_EXTRA_PUSH_TOKEN

public static final java.lang.String INTENT_PUSH_TOKEN_CHANGED_EXTRA_PUSH_TOKEN

The extra key for the new push token, can be null.

See Also:

Constant Field Values

INTENT_NOTIFICATION_OPENED

public static final java.lang.String INTENT_NOTIFICATION_OPENED

Local intent broadcasted when a push notification created by the WonderPush SDK has been opened.

See Also:

Constant Field Values

INTENT_NOTIFICATION_OPENED_EXTRA_RECEIVED_PUSH_NOTIFICATION

public static final java.lang.String INTENT_NOTIFICATION_OPENED_EXTRA_RECEIVED_PUSH_NOTIFICATION

The extra key for the original received push notification intent in a INTENT_NOTIFICATION_OPENED intent.

See Also:

Constant Field Values

INTENT_NOTIFICATION_OPENED_EXTRA_FROM_USER_INTERACTION

public static final java.lang.String INTENT_NOTIFICATION_OPENED_EXTRA_FROM_USER_INTERACTION

The extra key for whether the user clicked the notification or it was automatically opened by the SDK in a INTENT_NOTIFICATION_OPENED intent.

See Also:

Constant Field Values

INTENT_NOTIFICATION_OPENED_EXTRA_BUTTON_INDEX

public static final java.lang.String INTENT_NOTIFICATION_OPENED_EXTRA_BUTTON_INDEX

The extra key indicating which action button the user clicked on the notification in a INTENT_NOTIFICATION_WILL_OPEN intent.

See Also:

Constant Field Values

INTENT_NOTIFICATION_WILL_OPEN

public static final java.lang.String INTENT_NOTIFICATION_WILL_OPEN

Local intent broadcasted when a push notification created by the WonderPush SDK is to be opened, but no activity is to be started. This let's you handle data notifications or any deep linking yourself.

See Also:

Constant Field Values

INTENT_NOTIFICATION_WILL_OPEN_EXTRA_RECEIVED_PUSH_NOTIFICATION

public static final java.lang.String INTENT_NOTIFICATION_WILL_OPEN_EXTRA_RECEIVED_PUSH_NOTIFICATION

The extra key for the original received push notification intent in a INTENT_NOTIFICATION_WILL_OPEN intent.

See Also:

Constant Field Values

INTENT_NOTIFICATION_WILL_OPEN_EXTRA_FROM_USER_INTERACTION

public static final java.lang.String INTENT_NOTIFICATION_WILL_OPEN_EXTRA_FROM_USER_INTERACTION

The extra key for whether the user clicked the notification or it was automatically opened by the SDK in a INTENT_NOTIFICATION_WILL_OPEN intent.

See Also:

Constant Field Values

INTENT_NOTIFICATION_WILL_OPEN_EXTRA_AUTOMATIC_OPEN

public static final java.lang.String INTENT_NOTIFICATION_WILL_OPEN_EXTRA_AUTOMATIC_OPEN

The extra key denoting whether to automatically display a rich notification message in a INTENT_NOTIFICATION_WILL_OPEN intent. You can set this property to false in your BroadcastReceiver.

See Also:

Constant Field Values

INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE

public static final java.lang.String INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE

The extra key denoting the received push notification type, for a INTENT_NOTIFICATION_WILL_OPEN intent. You can test this property against INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE_DATA in your BroadcastReceiver.

See Also:

Constant Field Values

INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE_DATA

public static final java.lang.String INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE_DATA

The value associated to data push notifications (aka silent notifications), corresponding to the extra key INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE.

See Also:

Constant Field Values

INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_ACTION

public static final java.lang.String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_ACTION

Intent action for notification button action `method`.

See Also:

Constant Field Values

INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_SCHEME

public static final java.lang.String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_SCHEME

Intent scheme for notification button action `method`.

See Also:

Constant Field Values

INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_AUTHORITY

public static final java.lang.String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_AUTHORITY

Intent authority for notification button action `method`.

See Also:

Constant Field Values

INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_METHOD

public static final java.lang.String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_METHOD

Intent query parameter key for the notification button action `method` method name.

See Also:

Constant Field Values

INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_ARG

public static final java.lang.String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_ARG

Intent query parameter key for the notification button action `method` argument.

See Also:

Constant Field Values

Method Detail

setLogging

public static void setLogging(boolean enable)

Whether to enable debug logging. You should not do this in production builds.

Parameters:

enable - true to enable debug logs.

showPotentialNotification

public static boolean showPotentialNotification(android.app.Activity activity,
                                                android.content.Intent intent)

Method to call on your onNewIntent() and onCreate() methods to handle the WonderPush notification.

Starting from API 14, there is no need to call this method, but it won't hurt if you do.

This method is automatically called from within initialize(Context), so calling this method after calling initialize(Context) is useless.

Example:

 
 @Override
 protected void onCreate(Bundle savedInstance) {
     // In case you call WonderPush.initialize() from your custom Application class,
     // and you target API < 14, you can either call WonderPush.initialize() once again here
     // or call this method instead.
     WonderPush.showPotentialNotification(this, getIntent());
 }

 @Override
 protected void onNewIntent(Intent intent) {
     WonderPush.showPotentialNotification(this, intent);
 }
 
 

Parameters:

activity - The current Activity. Just give this.

intent - The intent the activity received. Just give the intent you received in parameter, or give getIntent().

Returns:

true if handled, false otherwise.

getInstallationCustomProperties

public static org.json.JSONObject getInstallationCustomProperties()

Returns the latest known custom properties attached to the current installation object stored by WonderPush.

putInstallationCustomProperties

public static void putInstallationCustomProperties(org.json.JSONObject customProperties)

Update the custom properties attached to the current installation object stored by WonderPush.

In order to remove a value, don't forget to use the JSONObject.NULL object as value.

Parameters:

customProperties - The partial object containing only the properties to update.

trackEvent

public static void trackEvent(java.lang.String type)

Send an event to be tracked to WonderPush.

Parameters:

type - The event type, or name. Event types starting with an @ character are reserved.

trackEvent

public static void trackEvent(java.lang.String type,
                              org.json.JSONObject customData)

Send an event to be tracked to WonderPush.

Parameters:

type - The event type, or name. Event types starting with an @ character are reserved.

customData - A JSON object containing custom properties to be attached to the event. Prefer using a few custom properties over a plethora of event type variants.

isReady

public static boolean isReady()

Whether the SDK is ready to operate and the INTENT_INTIALIZED intent has been dispatched. The SDK is ready when it is initialized and has fetched an access token.

Returns:

true if the SDK is ready, false otherwise.

initialize

public static void initialize(android.content.Context context)

Initialize WonderPush.
Call this method before using WonderPush.

A good place to initialize WonderPush is in your main activity's onCreate(Bundle) method as follows:

protected void onCreate(Bundle savedInstance) {
    WonderPush.initialize(this);
}

This function will instantiate the WonderPushInitializer implementation you provided in your AndroidManifest.xml.
Please look at that interface documentation for detailed instruction.

Parameters:

context - The main Activity of your application, or failing that, the Application context. It must be the same activity that you declared in the <meta-data> tag under the WonderPush <receiver> tag in your AndroidManifest.xml.

initialize

public static void initialize(android.content.Context context,
                              java.lang.String clientId,
                              java.lang.String clientSecret)

Initialize WonderPush from your WonderPushInitializer implementation.

Prefer calling the simpler initialize(Context) function directly, as it will instantiate your WonderPushInitializer implementation which will in turn call this function. This way you concentrate the retrieval of your credentials from secure storage in a single location.

Parameters:

context - The main Activity of your application, or failing that, the Application context.

clientId - The clientId of your application.

clientSecret - The clientSecret of your application.

setUserId

public static void setUserId(java.lang.String userId)

Sets the user id, used to identify a single identity across multiple devices, and to correctly identify multiple users on a single device.

If not called, the last used user id it assumed. Defaulting to null if none is known.

Prefer calling this method just before calling initialize(Context), rather than just after.

Upon changing userId, the access token is wiped, so avoid unnecessary calls, like calling with null just before calling with a user id.

Parameters:

userId - The user id, unique to your application. Use null for anonymous users.
You are strongly encouraged to use your own unique internal identifier.

getUserId

public static java.lang.String getUserId()

Gets the user id, used to identify a single identity across multiple devices, and to correctly identify multiple users on a single device.

You should not call this method before initializing the SDK.

Returns:

The user id, which may be null for anonymous users.

See Also:

setUserId(String), initialize(Context)

getDeviceId

public static java.lang.String getDeviceId()

Gets the device id, used to identify a single device across applications, and to correctly identify multiple users on a single device.

You should not call this method before initializing the SDK.

Because of the way our device id is build, it is populated asynchronously, so you may get a null response even a few moments after calling initialize(Context). You can either wait a bit (1 second should be enough on modern devices), or wait for isReady() to return true, which may take some more time on the first launch, especially is the network connection is bad.

Returns:

The device id, or null if the SDK is not initialized.

See Also:

isReady(), initialize(Context)

getInstallationId

public static java.lang.String getInstallationId()

Gets the device id, used to identify a single device across applications, and to correctly identify multiple users on a single device.

You should not call this method before the SDK is ready.

Returns:

The device id, or null if the SDK is not initialized.

See Also:

isReady()

getPushToken

public static java.lang.String getPushToken()

Gets the push token, used to send notification to this installation.

You should not call this method before initializing the SDK.

Returns:

The push token, or null if the installation is not yet registered to push notifications, or has not finished refreshing the push token after a forced update.

getAccessToken

public static java.lang.String getAccessToken()

Gets the access token, used to grant access to the current installation to the WonderPush REST API.

You should not call this method before the SDK is ready.

This together with your client secret gives entire control to the current installation and the associated user, you should not disclose it unnecessarily.

Returns:

The access token, or null if the SDK is not initialized.

See Also:

isReady()

onBroadcastReceived

public static boolean onBroadcastReceived(android.content.Context context,
                                          android.content.Intent intent,
                                          int iconResource,
                                          java.lang.Class<? extends android.app.Activity> activityClass)

Method to be called in your own Google Cloud Messaging BroadcastReceiver to handle WonderPush push notifications.

Note: This is only needed if you use your own BroadcastReceiver, as previously advertised in the guide.

Implement your BroadcastReceiver.onReceive(Context, Intent) method as follows:

public void onReceive(Context context, Intent intent) {
    if (WonderPush.onBroadcastReceived(context, intent, R.drawable.icon, YourMainActivity.class)) {
        return;
    }
    // Do your own handling here
}

For more information about Google Cloud Messaging visit: https://developers.google.com/cloud-messaging/android/client.

Parameters:

context - The current context.

intent - The received intent.

iconResource - The icon you want to show in the notification.

activityClass - The activity class you want to start when the user touches the notification

Returns:

true if handled, false otherwise.

getNotificationEnabled

public static boolean getNotificationEnabled()

Returns whether push notification are enabled.

Returns:

true by default as no explicit user permission is required.

setNotificationEnabled

public static void setNotificationEnabled(boolean status)

Sets whether to enable push notifications for the current device.

Parameters:

status - false to opt out of push notifications.