Documentation

← Back to Push Notifications for WordPress

Table of Contents

  1. Getting Started
  2. Install and Activate Push Notifications for WordPress
  3. Configure Push Notifications for WordPress
  4. APIs
  5. App Subscribers
  6. Manage user categories
  7. OAuth & API Keys
  8. WPML Compatibility
  9. Test a Push Notification
  10. Examples of Notification Payloads
  11. Devices without token
  12. Migrating from HTTP to HTTPS
  13. Android Library
  14. iOS Library
  15. Hooks and functions
  16. Uninstall Push Notifications for WordPress
  17. Migrating from Push Notification for Posts to Push Notification for WordPress

1) Getting Started

  1. Install this plugin on your WordPress site (see below).
  2. Change the WordPress permalink structure (Settings → Permalinks) from "default" to one of the so-called "pretty" permalinks.
  3. Enable the post/custom post types for which you want to send notifications on the plugin's settings page.

For iOS and Android notifications:

  1. Enable push notifications on the plugin's settings page (providing required certificates and keys, see below).
  2. Build your iOS and/or Android apps. Being a mobile developer, you should know how to do that (or request a quote from our team).
  3. Connect the apps to your WordPress site using the Register API (see below).

Now, when users launch the apps, their devices will automatically register to your site. As soon as a new post is published, a push notification is sent to registered devices, with the title of the post (configurable):

New Post

Notification

For Safari and Web Push notifications (Premium only):

  1. Migrate your website from HTTP to HTTPS (see below)
  2. Enable push notifications on the plugin's settings page (providing required certificates and keys, see below).

Now, when users open the website, they will receive a prompt asking them if they'd like to turn them on:

pnfw-chrome-prompt

2) Install and Activate Push Notifications for WordPress

Push Notifications for WordPress installs and activates just like any other WordPress plugin:

  1. You can download the plugin when you initially purchase the plugin or at anytime via the Account page.
  2. Go to the WordPress administration panel and select "Add New" under the Plugins navigation.
  3. On the Install Plugins page, click on the "upload" link (below the page title) and you will be presented with a file upload form.
  4. Click the "Browse..." button and then select the plugin zip file from your computer and then click the "ok" or "open" button (depending on browser).
  5. Once the file has been selected you can then click on the "Install Now" button to upload the plugin. WordPress will upload and unzip the plugin file.

Once Push Notifications for WordPress has been uploaded you will be presented with a confirmation screen that the plugin was installed successfully. You will now need to activate the plugin. On the upload confirmation screen you will see an "Activate Plugin" link that you will need to click on in order to activate the plugin.

3) Configure Push Notifications for WordPress

Now that Push Notifications for WordPress is installed and active you will need to configure it through this page:

Settings

To send push notifications to iOS devices, you need the Apple Push Notification service SSL certificate in the .PEM format. For more information, see our Configuring iOS Push Notifications guide.

To send push notifications to Android devices, you need to obtain the Google API Key. For more information, see our Configuring Android Push Notifications guide.

To send push notifications to Safari devices, you need the Apple Push Notification service SSL certificate in the .PEM and .P12 format. For more information, see our Configuring Safari Push Notifications guide.

To send push notifications to devices supporting Web Push protocol, you need to obtain and provide VAPID keys. For more information, see our Configuring Web Push Notifications guide.

4) APIs

This plugin provides easy to use REST APIs, available via HTTP.

Note: The APIs can be protected from abuse through OAuth 1.0a one-legged.

4.1) Register API

To send a push notification to a device, we must know its token (or Device ID) which has to be provided by the app through this API. This API allows client device to register itself to Push Notifications for WordPress so that it can receive future notifications.

URL structure:
http://yoursite/pnfw/register/
Method:
POST
Parameters:
  • token (string): token given by APNs or FCM identifying the device, often called device ID (read here for devices without token, e.g. iOS simulator).
  • prevToken (string, optional): the old token used by the device. If set, the server will update the existing token with the new one. Please note: prevToken should be different from token, otherwise nothing is done.
  • os (string): operating system. It must be iOS or Android (case sensitive).
  • email (string, optional): the user email address.
  • userCategory (number, optional): the user category ID. (Premium only)
  • lang (string, optional): two-letter code for the device language (e.g.: en, de, fr, it), i.e. the language in which the user would like to receive the content and notifications (Premium only). Requires WPML in order to work.

You can add any custom fields to registered subscribers using the hook pnfw_register_custom_parameters (Premium only).

Sample request for new registration:
POST /pnfw/register/ HTTP/1.1
Host: yoursite
Content-Length: 26
Content-Type: application/x-www-form-urlencoded

token=new_device_id&os=iOS
Sample request for updating registration:
POST /pnfw/register/ HTTP/1.1
Host: yoursite
Content-Length: 50
Content-Type: application/x-www-form-urlencoded

prevToken=old_device_id&token=new_device_id&os=iOS
Returns:
  • 200 OK: on success.
  • 401 Unauthorized: if OAuth is enabled but the signature is invalid (see below).
  • 404 Not Found: if prevToken is not found on updating registration.
  • 500 Internal Server Error: on missing mandatory parameters, unknown operating system, or general failure.
On errors:

On errors, besides the HTTP status codes defined above, a JSON is returned with this format:

{
	"error" : "401", // the error code (string, coincides with the HTTP status code)
	"reason" : "Unauthorized", // the reason of the error (string)
	"detail" : "oauth_consumer_key parameter is missing" // a human-readable
	// explanation of the error (string)
}

Note: The detail could change at any time so applications should not depend on the actual message text.

Registered devices will appear in the Tokens page:

Tokens

4.2) Posts API (list)

This API returns a list of posts/custom post types filtered for the specified device token (i.e. user/device). For each post are returned only basic information.

URL structure:
http://yoursite/pnfw/posts/
Method:
GET
Parameters:
  • token (string): token given by APNs or FCM identifying the device, often called device ID (read here for devices without token, e.g. iOS simulator).
  • os (string): operating system. It must be iOS or Android (case sensitive).
  • lang (string, optional): two-letter code for the device language (e.g.: en, de, fr, it), i.e. the language in which the user would like to receive the content and notifications (Premium only). Requires WPML in order to work.
Sample request:
GET /pnfw/posts/?token=device_id&os=iOS HTTP/1.1
Host: yoursite
Returns:
  • 200 OK: on success.
  • 401 Unauthorized: if OAuth is enabled but the signature is invalid (see below).
  • 500 Internal Server Error: on missing mandatory parameters, unknown operating system, or general failure.
Sample successful response:
{  
   "posts" : [  
      {  
         "id" : 116,
         "title" : "This is the second post",
         "thumbnail" : "http://yoursite/wp-content/uploads/image2-small.jpeg",
         "read" : false // omitted if true
      },
      {  
         "id" : 115,
         "title" : "This is the first post",
         "thumbnail" : "http://yoursite/wp-content/uploads/image1-small.jpeg"
      },
   ],
   "timestamp" : 1428397161
}
On errors:

On errors, besides the HTTP status codes defined above, a JSON is returned with this format:

{
	"error" : "401", // the error code (string, coincides with the HTTP status code)
	"reason" : "Unauthorized", // the reason of the error (string)
	"detail" : "oauth_consumer_key parameter is missing" // a human-readable
	// explanation of the error (string)
}

Note: The detail could change at any time so applications should not depend on the actual message text.

4.3) Posts API (details)

This API returns the details of the specified post/custom post type.

URL structure:
http://yoursite/pnfw/posts/
Method:
GET
Parameters:
  • id (integer): the ID of the post/custom post type to fetch.
  • token (string): token given by APNs or FCM identifying the device, often called device ID (read here for devices without token, e.g. iOS simulator).
  • os (string): operating system. It must be iOS or Android (case sensitive).
  • lang (string, optional): two-letter code for the device language (e.g.: en, de, fr, it), i.e. the language in which the user would like to receive the content and notifications (Premium only). Requires WPML in order to work.

When this API is called, the post is considered "read" by this specific device token–and consequently by the corresponding user. Therefore, the statistics and the badge on iOS are updated.

Sample request:
GET /pnfw/posts/?token=device_id&os=iOS&id=115 HTTP/1.1
Host: yoursite
Returns:
  • 200 OK: on success.
  • 401 Unauthorized: if OAuth is enabled but the signature is invalid (see below).
  • 500 Internal Server Error: on missing mandatory parameters, unknown operating system, or general failure.
Sample successful response:
{  
   "title":"This is the first post",
   "content":"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
   "categories":["Breaking"],
   "author":"Delite Studio",
   "image":"http://yoursite/wp-content/uploads/image1-large.jpeg"
}

The categories field is valued correctly only if you enable the corresponding taxonomy in the plugin's Settings page under "Categories Filterable by App Subscribers."

On errors:

On errors, besides the HTTP status codes defined above, a JSON is returned with this format:

{
	"error" : "401", // the error code (string, coincides with the HTTP status code)
	"reason" : "Unauthorized", // the reason of the error (string)
	"detail" : "oauth_consumer_key parameter is missing" // a human-readable
	// explanation of the error (string)
}

Note: The detail could change at any time so applications should not depend on the actual message text.

4.4) Posts API (POST)

This API allows client device to set the flag read/unread of a post.

URL structure:
http://yoursite/pnfw/posts/
Method:
POST
Parameters:
  • token (string): token given by APNs or FCM identifying the device, often called device ID (read here for devices without token, e.g. iOS simulator).
  • os (string): operating system. It must be iOS or Android (case sensitive).
  • id (number): the ID of the post.
  • viewed (boolean): whether or not the post has to be set as viewed.
  • lang (string, optional): two-letter code for the device language (e.g.: en, de, fr, it), i.e. the language in which the user would like to receive the content and notifications (Premium only). Requires WPML in order to work.
Sample request:
POST /pnfw/posts/ HTTP/1.1
Host: yoursite
Content-Length: 40
Content-Type: application/x-www-form-urlencoded

token=device_id&os=iOS&id=3&viewed=true
Returns:
  • 200 OK: on success.
  • 401 Unauthorized: if OAuth is enabled but the signature is invalid (see below).
  • 404 Not Found: if the specified id is not valid.
  • 500 Internal Server Error: on missing mandatory parameters, unknown operating system, or general failure.
On errors:

On errors, besides the HTTP status codes defined above, a JSON is returned with this format:

{
	"error" : "401", // the error code (string, coincides with the HTTP status code)
	"reason" : "Unauthorized", // the reason of the error (string)
	"detail" : "oauth_consumer_key parameter is missing" // a human-readable
	// explanation of the error (string)
}

Note: The detail could change at any time so applications should not depend on the actual message text.

4.5) Categories API (GET)

This API allows client device to retrieve the list of post categories.

URL structure:
http://yoursite/pnfw/categories/
Methods:
GET
Parameters:
  • token (string): token given by APNs or FCM identifying the device, often called device ID (read here for devices without token, e.g. iOS simulator).
  • os (string): operating system. It must be iOS or Android (case sensitive).
  • lang (string, optional): two-letter code for the device language (e.g.: en, de, fr, it), i.e. the language in which the user would like to receive the content and notifications (Premium only). Requires WPML in order to work.
Sample request:
GET /pnfw/categories/?token=device_id&os=iOS HTTP/1.1
Host: yoursite
Returns:
  • 200 OK: on success.
  • 401 Unauthorized: if OAuth is enabled but the signature is invalid (see below).
  • 500 Internal Server Error: on missing mandatory parameters, unknown operating system, or general failure.
Sample successful response:
{
	"categories": [
		{"id" : 1, "name" : "Breaking", "parent" : 0, "description" : "The latest breaking
		news around the world", "exclude" : false},
		{"id" : 2, "name" : "Exclusive", "parent" : 0, "exclude" : false},
		{"id" : 3, "name" : "Featured", "parent" : 0, "exclude" : true}
	],
	"timestamp" : 1423477714
}
On errors:

On errors, besides the HTTP status codes defined above, a JSON is returned with this format:

{
	"error" : "401", // the error code (string, coincides with the HTTP status code)
	"reason" : "Unauthorized", // the reason of the error (string)
	"detail" : "oauth_consumer_key parameter is missing" // a human-readable
	// explanation of the error (string)
}

Note: The detail could change at any time so applications should not depend on the actual message text.

4.6) Categories API (POST)

This API allows client device to set posts categories of which wants to receive push notifications.

URL structure:
http://yoursite/pnfw/categories/
Methods:
POST
Parameters:
  • token (string): token given by APNs or FCM identifying the device, often called device ID (read here for devices without token, e.g. iOS simulator).
  • os (string): operating system. It must be iOS or Android (case sensitive).
  • id (number): the category ID.
  • exclude (boolean): whether or not the device will be excluded from receiving push notifications in that category.
  • lang (string, optional): two-letter code for the device language (e.g.: en, de, fr, it), i.e. the language in which the user would like to receive the content and notifications (Premium only). Requires WPML in order to work.

To exclude/include multiple categories, simply call this API multiple times.

Sample request:
POST /pnfw/categories/ HTTP/1.1
Host: yoursite
Content-Length: 41
Content-Type: application/x-www-form-urlencoded

token=device_id&os=iOS&id=3&exclude=true
Returns:
  • 200 OK: on success.
  • 401 Unauthorized: if OAuth is enabled but the signature is invalid (see below).
  • 500 Internal Server Error: on missing mandatory parameters, unknown operating system, or general failure.
On errors:

On errors, besides the HTTP status codes defined above, a JSON is returned with this format:

{
	"error" : "401", // the error code (string, coincides with the HTTP status code)
	"reason" : "Unauthorized", // the reason of the error (string)
	"detail" : "oauth_consumer_key parameter is missing" // a human-readable
	// explanation of the error (string)
}

Note: The detail could change at any time so applications should not depend on the actual message text.

4.7) User Categories API (GET) (Premium only)

This API allows client device to retrieve the list of user categories.

URL structure:
http://yoursite/pnfw/user-categories/
Method:
GET
Parameters:
  • token (string): token given by APNs or FCM identifying the device, often called device ID (read here for devices without token, e.g. iOS simulator).
  • os (string): operating system. It must be iOS or Android (case sensitive).
  • lang (string, optional): two-letter code for the device language (e.g.: en, de, fr, it), i.e. the language in which the user would like to receive the content and notifications (Premium only). Requires WPML in order to work.
Sample request:
GET /pnfw/user-categories/?token=device_id&os=iOS HTTP/1.1
Host: yoursite
Returns:
  • 200 OK: on success.
  • 401 Unauthorized: if OAuth is enabled but the signature is invalid (see below).
  • 500 Internal Server Error: on missing mandatory parameters, unknown operating system, or general failure.
Sample successful response:
{  
   "categories":[  
      {  
         "id":79,
         "name":"VIPs"
         "description":"Person who is accorded special privileges."
      },
      {  
         "id":80,
         "name":"Fans"
      },
      {  
         "id":81,
         "name":"Readers"
      }
   ],
   "timestamp":1440239384
}
On errors:

On errors, besides the HTTP status codes defined above, a JSON is returned with this format:

{
	"error" : "401", // the error code (string, coincides with the HTTP status code)
	"reason" : "Unauthorized", // the reason of the error (string)
	"detail" : "oauth_consumer_key parameter is missing" // a human-readable
	// explanation of the error (string)
}

Note: The detail could change at any time so applications should not depend on the actual message text.

4.8) User Categories API (POST) (Premium only)

This API allows client device to set the user category. The oldest categories are overwritten.

URL structure:
http://yoursite/pnfw/user-categories/
Method:
POST
Parameters:
  • token (string): token given by APNs or FCM identifying the device, often called device ID (read here for devices without token, e.g. iOS simulator).
  • os (string): operating system. It must be iOS or Android (case sensitive).
  • id (number): the user category ID.
  • lang (string, optional): two-letter code for the device language (e.g.: en, de, fr, it), i.e. the language in which the user would like to receive the content and notifications (Premium only). Requires WPML in order to work.
Sample request:
POST /pnfw/user-categories/ HTTP/1.1
Host: yoursite
Content-Length: 41
Content-Type: application/x-www-form-urlencoded

token=device_id&os=iOS&id=3
Returns:
  • 200 OK: on success.
  • 401 Unauthorized: if OAuth is enabled but the signature is invalid (see below).
  • 404 Not Found: if the specified id is not valid.
  • 500 Internal Server Error: on missing mandatory parameters, unknown operating system, or general failure.
On errors:

On errors, besides the HTTP status codes defined above, a JSON is returned with this format:

{
	"error" : "401", // the error code (string, coincides with the HTTP status code)
	"reason" : "Unauthorized", // the reason of the error (string)
	"detail" : "oauth_consumer_key parameter is missing" // a human-readable
	// explanation of the error (string)
}

Note: The detail could change at any time so applications should not depend on the actual message text.

4.9) Unregister API

This API allows client device to unregister itself from push notifications. If the last token associated with an anonymous user is removed, the user is also removed.

URL structure:
http://yoursite/pnfw/unregister/
Methods:
POST
Parameters:
  • token (string): token given by APNs or FCM identifying the device, often called device ID (read here for devices without token, e.g. iOS simulator).
  • os (string): operating system. It must be iOS or Android (case sensitive).
  • lang (string, optional): two-letter code for the device language (e.g.: en, de, fr, it), i.e. the language in which the user would like to receive the content and notifications (Premium only). Requires WPML in order to work.
Sample request:
POST /pnfw/unregister/ HTTP/1.1
Host: yoursite
Content-Length: 41
Content-Type: application/x-www-form-urlencoded

token=device_id&os=iOS
Returns:
  • 200 OK: on success.
  • 401 Unauthorized: if OAuth is enabled but the signature is invalid (see below).
  • 500 Internal Server Error: on missing mandatory parameters, unknown operating system, or general failure.
On errors:

On errors, besides the HTTP status codes defined above, a JSON is returned with this format:

{
	"error" : "401", // the error code (string, coincides with the HTTP status code)
	"reason" : "Unauthorized", // the reason of the error (string)
	"detail" : "oauth_consumer_key parameter is missing" // a human-readable
	// explanation of the error (string)
}

Note: The detail could change at any time so applications should not depend on the actual message text.

5) App subscribers

Each token is associated with exactly one app subscriber. An app subscriber have 1 to N tokens. Users are automatically created with the Register API following this logic:

  • If the optional email parameter is not supplied an "anonymous" user is created, with role "App Subscriber" and without associated email address.
  • If the optional email parameter is provided a user is created with the specified address and role "App Subscriber." A welcome email is automatically sent to that address with the login details. If an app subscriber was already registered with that email address it is no longer created, but it is associated with the new token.

Note: Users who have specified the email address but have not confirmed it will not receive push notifications.

Registered app subscribers will appear in the App Subscribers page:

App Subscribers

6) Manage user categories (Premium only)

To create new user categories, you need to access the Users → Categories page first:

Users Categories

On the left side of the page you can create new user categories. Fill in the category name and press the Add New User Category button.

From the app, at any time you can get a list of the user categories using the User Categories (GET) API.

Now, when you publish a post/custom post type you can choose who should see it from the Push Notifications box on the right:

New Post

You can assign categories to app subscribers from the Push Notifications → App Subcribers page.

To bulk edit multiple users, select the users, select "Assign to..." from the drop down and click Apply.

Bulk Edit User Categories

Mass editing using bulk actions will come in handy when you need to make changes to many users quickly.

From the app, you can assign a user to a particular category using the User Categories (POST) API.

7) OAuth & API Keys

The APIs can be protected from abuse through OAuth 1.0a one-legged. Any request sent to the APIs that are not properly signed will be denied. In this way we can ensure that only authorized apps, who know the so-called "API Keys," can register. It is an optional possibility which we strongly encourage you to use (but that requires a little work client-side).

To enable OAuth, select the OAuth submenu and click on the Enable OAuth & Generate API Keys button:

OAuth

Now you should see two keys:

OAuth

These are your Consumer Key and Consumer Secret, and needs to be used by your apps. This is all you need to do server-side.

Once you have the Consumer Key and Consumer Secret you are now ready to start interacting with the APIs in a secure way. By this time, all calls that an app will do to the APIs must be signed following the OAuth 1.0a specifications (RFC5849). In short, a signature is created by using the request method, domain, the URI, and a sorted string of every parameter in the request (except the signature parameter itself). Once properly formatted, you create a base64-encoded HMAC-SHA1 or HMAC-SHA256 signature using your Consumer Secret key. For example, if you need to sign this call:

https://yourwebsite.com/pnfw/register/?
token=xxx&os=iOS&oauth_consumer_key=ck_yyy&oauth_timestamp=1522047414&
oauth_nonce=4BC8EBF2&oauth_signature_method=HMAC-SHA1

you must first sort alphabetically the parameters and calculate the signature on this:

https://yourwebsite.com/pnfw/register/?
oauth_consumer_key=ck_yyy&oauth_nonce=4BC8EBF2&oauth_signature_method=HMAC-SHA1&
oauth_timestamp=1522047414&os=iOS&token=xxx

The Consumer Secret can't be inferred from the signature so, even if the traffic is flowing unencrypted, no one can forge calls in your place.

Please note: The OAuth parameters must be added as query string parameters and not included in the Authorization header. This is because there is no reliable cross-platform way to get the raw request headers in WordPress.

Luckily, you do not have to do this work by hand. There are libraries for iOS and Android who do it for you (more info).

8) WPML Compatibility (Premium only)

Push Notifications for WordPress supports multilingual sites built with WPML, the WordPress Multilingual Plugin.

How does this work? In each call the device must specify the parameter lang, a two-letter code for the device language (e.g.: en, de, fr, it). This code is used in these cases:

  • By the GET APIs (ie: Categories, Posts) to provide results in the requested language.
  • Sending push notifications.

If the content is not available in the requested language, the default language is used. The language is associated to the token, i.e. to the device.

Please note: when WPML is active, active custom post types and taxonomies must be set as translatable in WPML → Translation options.

9) Test a Push Notification

You can test a push notification through the Tokens page:

Test Push Notification

10) Examples of Notification Payloads

An iOS device receives a notification with a JSON payload formatted in this way:

{
	"aps" : {
		"alert" : "This is a new post",
		"badge" : 1,
		"sound" = "default",
	},
	"id" = "805",
}

Where:

  • alert (string): the title of the post.
  • badge (number): the number to display as the badge of the application icon (i.e. the number of unread notifications).
  • sound (string): the name of a sound file in the application bundle (you can change it in the Settings page under the iOS tab).
  • id (string): the ID of the post. It is useful to uniquely identify the post (or the custom post type) to which the notification relates and to ask the server for more details.

You can add custom fields to the payload using the hook pnfw_notification_payload (Premium only).

Note: in iOS 8 and later, the maximum size allowed for a notification payload is 2 kilobytes. Apple Push Notification service refuses any notification that exceeds this limit. (Prior to iOS 8 and in macOS, the maximum payload size is 256 bytes.)

An Android device receives a notification with the following key/value pairs:

  • title (string): the title of the post.
  • id (string): the ID of the post. It is useful to uniquely identify the post (or the custom post type) to which the notification relates and to ask the server for more details.

Note: Some third-party frameworks (e.g. Apache Cordova with PushPlugin) require that there is also a message field. In this case go to Push Notifications → Settings → Android tab and check the "In the Android notification payload add the message field" option.

Note: the maximum size allowed for a notification payload is 4096 bytes on Android.

11) Devices without token

Push Notifications for WordPress also supports devices without token, such as the iOS simulator, or iOS devices for which the user has not granted the ability to receive push notifications.

For these devices you can call the usual APIs, with one difference: the token passed to the Register API must be generated by the device itself by following these rules:

tokenless_milliseconds since Jan 01 1970 (UTC) (13 digit timestamp)

For example:

tokenless_1432285526694

Here is the code you can use on iOS:

NSString *token = [NSString stringWithFormat:@"tokenless_%lld",
	(long long)([[NSDate date] timeIntervalSince1970] * 1000.0)];

Thus Push Notifications for WordPress will respond properly to all the APIs--as if it were a normal device--but never send push notifications to it.

12) Migrating from HTTP to HTTPS

You do not need to spend a fortune for the SSL certificate--there are some cheap options available. For example, Namecheap offers domain-level SSL certificates starting from $9.00/yr. Please note a dedicated IP is also highly recommended.

Beyond the Safari, Chrome, and Firefox notifications going HTTPS is a good thing: Google has announced that it will give you a ranking boost (more info here).

You can find some great tutorials, like this.

When you switch your site to HTTPS you should update your existing apps to connect to the HTTPS APIs. This obviously requires a certain time interval before they are available in stores and users update them.

Meantime you should:

  • Remember to not to automatically redirect on HTTPS the Push Notifications for WordPress APIs. You can do this in many ways, for example by adding a condition like this to your Apache rewrite rule: RewriteCond %{THE_REQUEST} !/pnfw/.
  • Remember, if you are using OAuth, to accept signed requests for both HTTP and HTTPS. Go to: Push Notifications → OAuth, and enable "Accept both HTTP and HTTPS requests".

13) Android Library

To simplify the integration of Push Notifications for WordPress in your Android app we provide a library available on this page. The library is free for buyers of the premium version.

14) iOS Library

To simplify the integration of Push Notifications for WordPress in your iOS app we provide a library available on this page. The library is free for buyers of the premium version.

15) Hooks and functions (Premium only)

Push Notifications for WordPress is an extensible framework with a large number of hooks in its source code. Using hooks you can add your own code to enhance what the plugin is doing in an easy way, maintaining compatibility with future updates. That makes it simple to integrate it with other plugins and find new ways to extend your site.

15.1) Add any custom fields to subscribers

You can add any custom fields to registered subscribers (i.e. not anonymous) using the hook pnfw_register_custom_parameters which you can use in this way:

add_filter('pnfw_register_custom_parameters',
 'my_register_custom_parameters');

function my_register_custom_parameters($parameters) {
	$par = array(
		'name' => 'age',
		'description' => 'Age',
		'required' => true,
		'overwrite' => true,
		'validate' => 'my_check_age');
	
	array_push($parameters, $par);
	
	return $parameters;
}

function my_check_age($age) {
	return ($age >= 0);
}

Where:

  • name (string): parameter name as it will be saved to the database. Use lowercase letters and separate words via underscores.
  • description (string): a human-friendly name which will be shown in the administration pages.
  • required (boolean): whether the parameter is mandatory or not.
  • overwrite (boolean): if set to true the previous value of the parameter, if present, is overwritten; if set to false the previous value of the parameter, if present, is left unchanged.
  • validate (function): function that takes the parameter and returns true if it is valid and false if not.

15.2) Add/remove custom fields to Posts API (details)

You can add/remove any custom fields to Posts API (details) using the hook pnfw_output_post_api which you can use in this way:

add_filter('pnfw_output_post_api', 'my_output_post_api');

function my_output_post_api($response) {
	unset($response['date']); // removes 'date' from the output JSON
	$response['permalink'] = get_permalink($response['id']); // adds 'permalink'
	// to the output JSON
		
	return $response;
}

Please note: $response is an array with keys and values.

15.3) Add/remove custom fields to Posts API (list)

You can add/remove any custom fields to Posts API (list) using the hook pnfw_output_posts_api which you can use in this way:

add_filter('pnfw_output_posts_api', 'my_output_posts_api');

function my_output_posts_api($response) {
	unset($response['date']); // removes 'date' from the output JSON
	$response['permalink'] = get_permalink($response['id']); // adds 'permalink'
	// to the output JSON
		
	return $response;
}

Please note: $response is an array with keys and values.

15.4) Customize the notifications title

You can customize the notifications title using the hook pnfw_notification_title which you can use in this way:

add_filter('pnfw_notification_title', 'my_notification_title', 10, 2);

function my_notification_title($title, $post_id) {
	return 'Overwritten for post ' . $post_id . ': ' . $title;
}

15.5) Add any custom fields to notification payload

You can add any custom fields to post notifications payload using the hook pnfw_notification_payload which you can use in this way:

add_filter('pnfw_notification_payload', 'my_notification_payload', 10, 2);

function my_notification_payload($payload, $post_id) {
	$payload['test'] = 'value';
	
	return $payload;
}

Where:

  • payload (array): the custom part of the payload (i.e. the part outside the aps dictionary on iOS).
  • post_id (integer): the post ID (or 0 for test notifications).

Please note: there are stringent limits on the payload size, so you should strive to keep it as small as possible.

Please note: custom fields are not available for notifications sent via the pnfw_send_notification() function.

Please note: custom fields are not available for Safari notifications.

15.6) Change field separator on CSV export

You can define a field separator other than the comma for the exported Comma-Separated Values (CSV) files in this way:

add_filter('pnfw_csv_separator', 'my_csv_separator');

function my_csv_separator($val) {
	return ";";
}

15.7) Send a push notification to all devices of the specified user

Send a push notification to all devices of the specified user.

The pnfw_send_notification() function currently does not support Chrome and Firefox notifications.

Declaration:
pnfw_send_notification($user_id, $message, $user_info)
Parameters:

$user_id: The ID of the WordPress user to which devices send the notification. Please note the user must be an app subscriber (info).
$message: The text of the message to send with the notification.
$user_info: An associative arrays of key/value pairs to be included in the notifications (see below). Default: array().

Notes:

$user_info is an associative arrays that is converted into JSON which may contain custom data which you app receiving the notification might use. Please note the maximum size allowed for a notification payload (including both $message and $user_info) is:

  • 256 bytes on iOS 7 or earlier
  • 2 kilobytes on iOS 8 and later
  • 4 kilobytes on Android
Sample:

Here is an example of the use that you can enter in the functions.php file of your theme:

add_action('woocommerce_order_status_completed',
   'mysite_woocommerce_order_status_completed');

function mysite_woocommerce_order_status_completed($order_id) {
    $order = new WC_Order($order_id);
    $user_id = $order->get_user_id();
    
    pnfw_send_notification($user_id, 'Your order is complete');
}

In this way when a WooCommerce order is completed a push notification is sent to the user's device(s).

16) Uninstall Push Notifications for WordPress

If you deactivate and delete Push Notifications for WordPress, we leave data created by the plugin. Although WordPress will tell you that we do remove data on uninstall, we don’t.

If you need to remove ALL Push Notifications for WordPress data, including tokens, users, analytics, and settings, go to: Push Notifications → Settings → Misc tab, and enable "Remove data on uninstall". Then when you deactivate and delete the plugin from the WordPress plugin admin, it will delete all data.

17) Migrating from Push Notification for Posts to Push Notification for WordPress

Yes. We have tried to make the process very simple.

Follow these steps:

  1. Backup your WordPress database as explained here.
  2. Upgrade Push Notification for Posts to version 2.0 or later without uninstalling previous version (very important: previous versions, when uninstalled, would remove all subscribers and tokens).
  3. Make sure the setting "Remove data on uninstall" is unchecked.
  4. Upload Push Notification for WordPress without activating it.
  5. Disable Push Notification for Posts.
  6. Activate Push Notification for WordPress.
  7. Uninstall Push Notification for Posts.

That's all! Enjoy all the advanced features of Push Notification for WordPress!