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:
//   composer require pusher/pusher-php-server

require __DIR__ . '/vendor/autoload.php';

$pusher = new Pusher\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'
        ),
      ),
    ),
  )
);
// 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"
      }
    }
  }
});
# 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'
          }
        }
      }
    })
  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'
      }
    }
  }
})
# 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'
      }
    }
  }
})

Didn’t receive a push notification? Check the debug console!

If you published something to the donuts interest, but your running app did not receive it, you can find out more by using the push notifications debug console. In the Pusher dashboard, visit your app, go to “Debug Console”, then choose the “Push Notifications” tab. This console will log any errors that happen when sending your push notifications.

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.

Custom data

Any custom data fields you wish to include in your push notification must be provided under a data key in the apns data structure. Any custom data fields specified outside of the data key won’t be pushed to the client.

{
  "apns": {
    "aps": {...},
    "data": {
      "foo": "bar"
    }
  }
}

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.