Package com.wonderpush.sdk

Class WonderPush

java.lang.Object
com.wonderpush.sdk.WonderPush
public class WonderPush extends 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 Details

    • INTENT_PUSH_TOKEN_CHANGED

      public static final String INTENT_PUSH_TOKEN_CHANGED
      Local intent broadcasted when the push token has changed.
      See Also:

    • INTENT_PUSH_TOKEN_CHANGED_EXTRA_OLD_KNOWN_PUSH_TOKEN

      public static final String INTENT_PUSH_TOKEN_CHANGED_EXTRA_OLD_KNOWN_PUSH_TOKEN
      The extra key for the previously known push token, can be null.
      See Also:

    • INTENT_PUSH_TOKEN_CHANGED_EXTRA_PUSH_TOKEN

      public static final String INTENT_PUSH_TOKEN_CHANGED_EXTRA_PUSH_TOKEN
      The extra key for the new push token, can be null.
      See Also:

    • INTENT_NOTIFICATION_OPENED

      public static final String INTENT_NOTIFICATION_OPENED
      Local intent broadcasted when a push notification created by the WonderPush SDK has been opened.
      See Also:

    • INTENT_NOTIFICATION_OPENED_EXTRA_RECEIVED_PUSH_NOTIFICATION

      public static final 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:

    • INTENT_NOTIFICATION_OPENED_EXTRA_NOTIFICATION_MODEL

      public static final String INTENT_NOTIFICATION_OPENED_EXTRA_NOTIFICATION_MODEL
      The extra key for the parsed notification in a INTENT_NOTIFICATION_OPENED intent.
      See Also:

    • INTENT_NOTIFICATION_OPENED_EXTRA_FROM_USER_INTERACTION

      public static final 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:

    • INTENT_NOTIFICATION_OPENED_EXTRA_BUTTON_INDEX

      public static final String INTENT_NOTIFICATION_OPENED_EXTRA_BUTTON_INDEX
      The extra key indicating which action button the user clicked on the notification in a INTENT_NOTIFICATION_OPENED intent.
      See Also:

    • INTENT_NOTIFICATION_WILL_OPEN

      public static final 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:

    • INTENT_NOTIFICATION_WILL_OPEN_EXTRA_RECEIVED_PUSH_NOTIFICATION

      public static final 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:

    • INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_MODEL

      public static final String INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_MODEL
      The extra key for the parsed notification in a INTENT_NOTIFICATION_WILL_OPEN intent.
      See Also:

    • INTENT_NOTIFICATION_WILL_OPEN_EXTRA_FROM_USER_INTERACTION

      public static final 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:

    • INTENT_NOTIFICATION_WILL_OPEN_EXTRA_AUTOMATIC_OPEN

      public static final 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:

    • INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE

      public static final 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:

    • INTENT_NOTIFICATION_WILL_OPEN_EXTRA_NOTIFICATION_TYPE_DATA

      public static final 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:

    • INTENT_NOTIFICATION_WILL_OPEN_EXTRA_BUTTON_INDEX

      public static final String INTENT_NOTIFICATION_WILL_OPEN_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:

    • INTENT_EVENT_TRACKED

      public static final String INTENT_EVENT_TRACKED
      Local intent broadcast when an event is tracked by the WonderPush SDK.
      See Also:

    • INTENT_EVENT_TRACKED_EVENT_TYPE

      public static final String INTENT_EVENT_TRACKED_EVENT_TYPE
      Intent extra key holding the type of event being tracked.
      See Also:

    • INTENT_EVENT_TRACKED_CUSTOM_DATA

      public static final String INTENT_EVENT_TRACKED_CUSTOM_DATA
      Intent extra key holding custom data serialized as JSON of event being tracked.
      See Also:

    • INTENT_EVENT_TRACKED_OCCURRENCES

      public static final String INTENT_EVENT_TRACKED_OCCURRENCES
      Intent extra key holding occurences data serialized as JSON of event being tracked.
      See Also:

    • INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_ACTION

      public static final String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_ACTION
      Intent action for notification button action `method`.
      See Also:

    • INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_SCHEME

      public static final String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_SCHEME
      Intent scheme for notification button action `method`.
      See Also:

    • INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_AUTHORITY

      public static final String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_AUTHORITY
      Intent authority for notification button action `method`.
      See Also:

    • INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_METHOD

      public static final String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_METHOD
      Intent query parameter key for the notification button action `method` method name.
      See Also:

    • INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_ARG

      public static final String INTENT_NOTIFICATION_BUTTON_ACTION_METHOD_EXTRA_ARG
      Intent query parameter key for the notification button action `method` argument.
      See Also:

  • Method Details

    • 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.

    • getLogging

      public static boolean getLogging()
      Whether debug logging is enabled.

    • disableGeolocation

      public static void disableGeolocation()
      Disables the collection of the user's geolocation.

    • enableGeolocation

      public static void enableGeolocation()
      Enables the collection of the user's geolocation. You still need the appropriate geolocation permissions in your AndroidManifest.xml to be able to read the user's location.

    • setGeolocation

      public static void setGeolocation(android.location.Location location)
      Overrides the user's geolocation.

      Using this method you can have the user's location be set to wherever you want. This may be useful to use a pre-recorded location.

      Note that the value is not persisted.

      Parameters:
      location - The location to use as the user's current geolocation. Using null has the same effect as calling disableGeolocation().

    • setLocale

      public static void setLocale(String locale)
      Overrides the user's locale.

      You should use an xx-XX form of RFC 1766, composed of a lowercase ISO 639-1 language code, an underscore or a dash, and an uppercase ISO 3166-1 alpha-2 country code.

      Defaults to getting the language and country codes from the system default locale.

      Parameters:
      locale - The locale to use as the user's locale. Use null to disable the override.

    • getLocale

      public static String getLocale()
      Gets the user's locale, either as previously stored, or as guessed from the system.
      Returns:
      The user's locale.
      See Also:

    • setCountry

      public static void setCountry(String country)
      Overrides the user's country.

      You should use an ISO 3166-1 alpha-2 country code.

      Defaults to getting the country code from the system default locale.

      Parameters:
      country - The country to use as the user's country. Use null to disable the override.

    • getCountry

      public static String getCountry()
      Gets the user's country, either as previously stored, or as guessed from the system.
      Returns:
      The user's country.
      See Also:

    • setCurrency

      public static void setCurrency(String currency)
      Overrides the user's currency.

      You should use an ISO 4217 currency code.

      Defaults to getting the currency code from the system default locale.

      Parameters:
      currency - The currency to use as the user's currency. Use null to disable the override.

    • getCurrency

      public static String getCurrency()
      Gets the user's currency, either as previously stored, or as guessed from the system.
      Returns:
      The user's currency.
      See Also:

    • setTimeZone

      public static void setTimeZone(String timeZone)
      Overrides the user's timeZone.

      You should use an IANA time zone database codes, Continent/Country style preferably, abbreviations like CET, PST, UTC, which have the drawback of changing on daylight saving transitions.

      Defaults to getting the time zone code from the system default locale.

      Parameters:
      timeZone - The time zone to use as the user's time zone. Use null to disable the override.

    • getTimeZone

      public static String getTimeZone()
      Gets the user's time zone, either as previously stored, or as guessed from the system.
      Returns:
      The user's time zone.
      See Also:

    • getProperties

      public static org.json.JSONObject getProperties()
      Returns the latest known properties attached to the current installation object stored by WonderPush.

      Returns an empty JSONObject if called without required user consent.

    • putProperties

      public static void putProperties(org.json.JSONObject properties)
      Update the 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.

      Does nothing if called without required user consent.

      Parameters:
      properties - The partial object containing only the properties to update.

    • setProperty

      public static void setProperty(String field, Object value)
      Sets the value to a given property attached to the current installation object stored by WonderPush. The previous value is replaced entirely. The value can be a String, Boolean, Number (coerced to Long or Double), JSONObject, JSONArray, or JSONObject.NULL (which has the same effect as unsetProperty(String)).

      Does nothing if called without required user consent.

      Parameters:
      field - The name of the property to set
      value - The value to be set, can be an array or Collection

    • unsetProperty

      public static void unsetProperty(String field)
      Removes the value of a given property attached to the current installation object stored by WonderPush. The previous value is replaced with JSONObject.NULL.

      Does nothing if called without required user consent.

      Parameters:
      field - The name of the property to set

    • addProperty

      public static void addProperty(String field, Object value)
      Adds the value to a given property attached to the current installation object stored by WonderPush. The stored value is made an array if not already one. If the given value is an array, all its values are added. If a value is already present in the stored value, it won't be added.

      Does nothing if called without required user consent.

      Parameters:
      field - The name of the property to add values to
      value - The value(s) to be added, can be an array

    • removeProperty

      public static void removeProperty(String field, Object value)
      Removes the value from a given property attached to the current installation object stored by WonderPush. The stored value is made an array if not already one. If the given value is an array, all its values are removed. If a value is present multiple times in the stored value, they will all be removed.
      Parameters:
      field - The name of the property to remove values from
      value - The value(s) to be removed, can be an array

    • getPropertyValue

      public static Object getPropertyValue(String field)
      Returns the value of a given property attached to the current installation object stored by WonderPush. If the property stores an array, only the first value is returned. This way you don't have to deal with potential arrays if that property is not supposed to hold one. Returns JSONObject.NULL instead of null if the property is absent or has an empty array value.
      Parameters:
      field - The name of the property to read values from
      Returns:
      JSONObject.NULL or a single value stored in the property, never a JSONArray or null

    • getPropertyValues

      public static List<Object> getPropertyValues(String field)
      Returns an immutable list of the values of a given property attached to the current installation object stored by WonderPush. If the property does not store an array, a list is returned nevertheless. This way you don't have to deal with potential scalar values if that property is supposed to hold an array. Returns an empty list instead of JSONObject.NULL or null if the property is absent. Returns a list wrapping any scalar value held by the property.

      Note, the returned value is an immutable list.

      Parameters:
      field - The name of the property to read values from
      Returns:
      A possibly empty JSONArray of the values stored in the property, but never JSONObject.NULL nor null

    • getInstallationCustomProperties

      @Deprecated public static org.json.JSONObject getInstallationCustomProperties()
      Deprecated.
      Returns the latest known custom properties attached to the current installation object stored by WonderPush.

      Use getProperties() instead.

      Returns an empty JSONObject if called without required user consent.

      See Also:

    • putInstallationCustomProperties

      @Deprecated public static void putInstallationCustomProperties(org.json.JSONObject customProperties)
      Deprecated.
      Update the custom properties attached to the current installation object stored by WonderPush.

      Use putProperties(JSONObject) instead.

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

      Does nothing if called without required user consent.

      Parameters:
      customProperties - The partial object containing only the properties to update.
      See Also:

    • trackEvent

      public static void trackEvent(String type)
      Send an event to be tracked to WonderPush.

      Does nothing if called without required user consent.

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

    • trackEvent

      public static void trackEvent(String type, org.json.JSONObject attributes)
      Send an event to be tracked to WonderPush.

      Does nothing if called without required user consent.

      Parameters:
      type - The event type, or name. Event types starting with an @ character are reserved.
      attributes - A JSON object containing attributes to be attached to the event. Prefer using a few attributes over a plethora of event type variants.

    • addTag

      public static void addTag(String... tag)
      Add one or more tags to the current installation object stored by WonderPush.

      Does nothing if called without required user consent.

      Parameters:
      tag - The tags to add to the installation.

    • removeTag

      public static void removeTag(String... tag)
      Remove one or more tags from the current installation object stored by WonderPush.

      Does nothing if called without required user consent.

      Parameters:
      tag - The tags to remove from the installation.

    • removeAllTags

      public static void removeAllTags()
      Remove all tags from the current installation object stored by WonderPush.

      Does nothing if called without required user consent.

    • getTags

      public static Set<String> getTags()
      Returns all the tags of the current installation object stored by WonderPush.
      Returns:
      A copy of the set of tags attached to the installation. Never returns null.

    • hasTag

      public static boolean hasTag(String tag)
      Test whether the current installation has the given tag attached to it.
      Parameters:
      tag - The tag to test.
      Returns:
      true if the given tag is attached to the installation, false otherwise.

    • initialize

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

      Using automatic initialization, you do not need to take care of this yourself. You must otherwise call this method before using the SDK. A good place for that is in the Application.onCreate() of your Application class.

      Parameters:
      context - And Activity or Application context.

    • initialize

      public static void initialize(android.content.Context context, String clientId, String clientSecret)
      Initialize WonderPush from your WonderPushInitializer implementation.

      Using automatic initialization, you do not need to take care of this yourself.

      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.

    • setRequiresUserConsent

      public static void setRequiresUserConsent(boolean value)
      Sets whether user consent is required before the SDK is allowed to work.

      Call this method before initialize(Context).

      Parameters:
      value - Whether user consent is required before the SDK is allowed to work.
      See Also:

    • getUserConsent

      public static boolean getUserConsent()
      Returns whether user consent has already provided consent.

      Call this method after initialize(Context).

    • setUserConsent

      public static void setUserConsent(boolean value)
      Provides or withdraws user consent.

      Call this method after initialize(Context).

      Parameters:
      value - Whether the user provided or withdrew consent.
      See Also:

    • downloadAllData

      public static void downloadAllData()
      Exports all data stored locally and on WonderPush servers and then starts a sharing activity for the user to save it.

      This method is blocking.

    • clearEventsHistory

      public static void clearEventsHistory()
      Ask the WonderPush servers to delete any event associated with the all local installations.

    • clearPreferences

      public static void clearPreferences()
      Ask the WonderPush servers to delete any custom data associated with the all local installations and related users.

    • clearAllData

      public static void clearAllData()
      Remove any local storage and ask the WonderPush servers to delete any data associated with the all local installations and related users.

    • clearAll

      public static void clearAll()
      Deprecated.
      Remove any local storage and ask the WonderPush servers to delete any data associated with the all local installations and related users.
      See Also:

    • setUserId

      public static void setUserId(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 push token is wiped, so avoid unnecessary calls, like calling with null just before calling with a user id. Successive calls with the same userId are fine.

      Changing the user id is akin to loading a new profile. A new installation will be created and no tags, properties or events will be kept. For more information, see our documentation.

      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 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:

    • getDeviceId

      public static String getDeviceId()
      Gets the device id, used to identify a single device, and to correctly identify multiple users on a single device.

      You should not call this method before initializing the SDK.

      Returns null if called without required user consent.

      Returns:
      The device id, or null if the SDK is not initialized.
      See Also:

    • getInstallationId

      public static 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 null if called without required user consent.

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

    • getPushToken

      public static String getPushToken()
      Gets the push token, used to send notification to this installation.

      You should not call this method before initializing the SDK.

      Returns null if called without required user consent.

      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 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 null if called without required user consent.

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

    • subscribeToNotifications

      public static void subscribeToNotifications(boolean fallbackToSettings)
      Enables push notifications for the current device
      Parameters:
      fallbackToSettings - Shows a dialog that leads user to the settings should he refuse the permission

    • subscribeToNotifications

      public static void subscribeToNotifications()
      Enables push notifications for the current device.

      Does nothing if called without required user consent.

    • unsubscribeFromNotifications

      public static void unsubscribeFromNotifications()
      Disables push notifications for the current device.

      Does nothing if called without required user consent.

    • isSubscribedToNotifications

      public static boolean isSubscribedToNotifications()
      Returns whether push notification are enabled.

      Returns false if called without required user consent.

      Returns:
      true by default as no explicit user permission is required, unless required user consent is lacking.

    • getNotificationEnabled

      @Deprecated public static boolean getNotificationEnabled()
      Deprecated.
      Returns whether push notification are enabled.

      Use isSubscribedToNotifications() instead.

      Returns false if called without required user consent.

      Returns:
      true by default as no explicit user permission is required, unless required user consent is lacking.
      See Also:

    • setNotificationEnabled

      @Deprecated public static void setNotificationEnabled(boolean status)
      Deprecated.
      Sets whether to enable push notifications for the current device.

      Use subscribeToNotifications() or unsubscribeFromNotifications() instead.

      Does nothing if called without required user consent.

      Parameters:
      status - false to opt out of push notifications.
      See Also:

    • setIntegrator

      public static void setIntegrator(String integrator)
      Sets the framework, library or wrapper used for integration. This method should not be used by the developer directly, only by components that facilitates the native SDK integration.
      Parameters:
      integrator - Expected format is "some-component-1.2.3"

    • getDelegate

      public static WonderPushDelegate getDelegate()
      Returns the configured delegate, or null if none was set.
      See Also:

    • setDelegate

      public static void setDelegate(WonderPushDelegate delegate)
      Configures a delegate for tighter integration with the SDK.

      Call this method as early as possible, like just before calling initialize(Context).

      Parameters:
      delegate - The new delegate to use.
      See Also: