Push Notifications: Pushing to your iOS client

Our Push Notifications system is currently in beta. This means you may experience errors, and the APIs may change. We would love to hear your feedback, so please get in touch!

Our Native Push Notifications API also supports iOS 10’s new rich content, including sending images, gifs and videos in your notifications! Check out our iOS 10 documentation..

Push notifications are triggered by your servers. After one of your iOS applications subscribes to an interest on our system, your server can then send a push notification to the iOS application by publishing to that interest. Your server can publish using one of our many official server libraries. This page guides you through setting up your server to send push notifications.

Note: Can’t see your server language here? We’re busy adding push notification features to our server libraries. If yours isn’t done yet, you can use our HTTP API directly.

Hello world example

To get started, let’s send the time-honored “hello world” message to your iOS application. We’ll assume your iOS application has subscribed to the interest "donuts". You can use any of the below examples - they will all trigger the same push notification.

// Install the server library with:
//   php composer.phar require 'pusher/pusher-php-server:2.5.*'

require('Pusher.php');

$pusher = new Pusher("APP_KEY", "APP_SECRET", "APP_ID", array('cluster' => 'APP_CLUSTER'));

$pusher->notify(
  array("donuts"),
  array(
    'apns' => array(
      'aps' => array(
        'alert' => array(
          'body' => 'hello world'
        ),
      ),
    ),
    'webhook_url' => 'https://example.com/endpoint',
    'webhook_level' => 'INFO',
  )
);
// Install the server library with:
//   npm install 'pusher@>=1.4.0'

var Pusher = require("pusher");

var pusher = new Pusher({
  appId: "APP_ID",
  key: "APP_KEY",
  secret: "APP_SECRET",
  cluster: "APP_CLUSTER"
});

pusher.notify(['donuts'], {
  apns: {
    aps: {
      alert: {
        body: "hello world"
      }
    }
  },
  webhook_url: "https://example.com/endpoint",
  webhook_level: "INFO"
});
# Install the server library with:
#   gem install pusher -v '>= 1.2.0'

require 'pusher'

pusher_client = Pusher::Client.new(
  app_id: 'APP_ID',
  key: 'APP_KEY',
  secret: 'APP_SECRET',
  cluster: 'APP_CLUSTER'
)

class HelloWorldController < ApplicationController
  def hello_world
    pusher_client.notify(["donuts"], {
      apns: {
        aps: {
          alert: {
            body: 'hello world'
          }
        }
      },
      webhook_url: 'https://example.com/endpoint',
      webhook_level: 'INFO'
    })
  end
end
# Install the server library with:
#   gem install pusher -v '>= 1.2.0'

require 'pusher'

pusher_client = Pusher::Client.new(
  app_id: 'APP_ID',
  key: 'APP_KEY',
  secret: 'APP_SECRET',
  cluster: 'APP_CLUSTER'
)

pusher_client.notify(["donuts"], {
  apns: {
    aps: {
      alert: {
        body: 'hello world'
      }
    }
  },
  webhook_url: 'https://example.com/endpoint',
  webhook_level: 'INFO'
})
# Install the server library with:
#   pip install 'pusher>=1.4' --upgrade

from pusher import Pusher

pusher = Pusher(app_id=u'APP_ID', key=u'APP_KEY', secret=u'APP_SECRET', cluster=u'APP_CLUSTER')

pusher.notify(['donuts'], {
  'apns': {
    'aps': {
      'alert': {
        'body': 'hello world'
      }
    }
  },
  'webhook_url': 'https://example.com/endpoint',
  'webhook_level': 'INFO'
})

Didn’t receive a push notification?

If you published something to the donuts interest, but your running app did not receive it, you can find out more by using webhooks. Alongside the "gcm" key in the body of your notification, you can provide a "webhook_url" and a "webhook_level". The snippets above tell Pusher to pass all errors to the URL https://example.com/endpoint.

To see the errors, replace that URL with one that you control. You can do this quickly and simply using RequestBin. Create a new bin, which will have its own URL like http://requestb.in/y0xssw70. Use that URL as your webhook_url, send your notification, then refresh the page on RequestBin. If Pusher encountered any errors while sending the notification, you will see information about them on your RequestBin page.

To see even more information, change the "webhook_level" value from "INFO" to "DEBUG". Pusher will then provide information for every push notification you send.

If you still did not receive a push notification, you can contact Pusher support.

Advanced options

Each of the notify methods accepts an object which specifies the message to send. This object is the language’s native representation of JSON. In the “hello world” examples above, the JSON description of our message was:

{
  "aps": {
    "alert": {
      "body": "hello world"
    }
  }
}

This is the simplest message you can send using APNs. There are many more advanced details you can specify. The full set of options for the APNs section of the notify call is described in Apple’s Payload Key Reference. For further examples, see Apple’s “Creating the Remote Notification Payload”. If you encounter error responses from the Push Notifications API, you may wish to consult Apple’s Push Notification troubleshooting guide.

Congratulations, you’ve completed the iOS push notifications guide! You can also set up your Android application by following our Android push notifications guide. After that, you can send to all your iOS and Android devices with a single call to notify!

Further reading

Have you tried using the search to find what you’re after? If you still have a question then get in touch with us and let us help you out.