Defining and Sending Push Notifications¶
The Urban Airship PHP Library strives to match the standard Urban Airship JSON format for specifying push notifications. When creating a push notification, you:
- Select the audience
- Define the notification payload
- Specify device types.
- Deliver the notification.
This example performs a broadcast with the same alert to all recipients and device types:
require_once 'vendor/autoload.php';
use Urbanairship\Airship;
use UrbanAirship\Push as P;
$response = $airship->push()
->setAudience(P\all)
->setNotification(P\notification("Hello, World!"))
->setDeviceTypes(P\all)
->send();
These selector functions are all in the Push namespace. It’s recommended to use a shortcut.
use UrbanAirship\Push as P;
Audience Selectors¶
An audience should specify one or more devices. An audience can be a device, such as a Channel; a tag, named user, or segment; a location; or a combination. Audience selectors are combined with and_, or_, and not_. All selectors are available in the Push namespace.
Simple Selectors¶
- all
Select all, to do a broadcast.
Used in both audience and deviceTypes.
$push->setAudience(P\all);
- iosChannel()
Select a single iOS channel.
$push->setAudience(P\iosChannel("8ac440cb-f148-4856-9631-3c8eb8d88d60"));
- androidChannel()
Select a single Android channel.
$push->setAudience(P\androidChannel("b8f9b663-0a3b-cf45-587a-be880946e880"));
- deviceToken()
Select a single iOS device token.
$push->setAudience(P\deviceToken("FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"));
- amazonChannel()
- Select a single Amazon channel.
- devicePin()
- Select a single BlackBerry PIN.
- apid()
- Select a single Android APID.
- wns()
- Select a single Windows 8 APID.
- mpns()
- Select a single Windows Phone 8 APID.
- tag()
- Select a single tag.
- named_user()
- Select a single named user.
- alias()
- Select a single alias.
- segment()
- Select a single segment.
Compound Selectors¶
- or_()
Select an audience that matches at least one of the given arguments.
$push->setAudience(P\or_(P\tag("foo"), P\tag("bar")));
- and_()
- Select an audience that matches all of the given arguments.
- not_()
Select an audience that does not match the given selector.
$push->setAudience(P\not(P\tag("foo")));
Location Selectors¶
- location()
Select a location expression.
Location expressions are made up of either an id or an alias and a time period specifier. Use one of the date specifier functions to return a properly formatted time specifier.
Produces a time specifier that represents relative amount of time, such as “the past three days”
- absoluteDate()
- Produces a time specifier that represents an absolute amount of time, such as from 2012-01-01 12:00 to 2012-01-01 12:00
Notifcation Payload¶
The notification payload determines what message and data is sent to a device. At its simplest, it consists of a single string-valued attribute, “alert”, which sends a push notification consisting of a single piece of text:
$push->setNotification(P\notification("Hello, world!"))
You can override the payload with platform-specific values as well.
- notification()
Creates a notification payload.
$push->setNotification(P\notification( "Hello others", array("ios"=>P\ios("Hello iOS", "+1"))))
- ios()
iOS/APNS specific platform override payload.
$push->setNotification(P\notification( null, array("ios"=>P\ios( "Hello iOS", "+1", "cow.caf", false, array("articleid" => "AB1234") )) ))
- android()
- Android specific platform override payload.
$push->setNotification(P\notification( null, array("android"=>P\android( "Hello Android", null, null, null, array("articleid" => "AB1234") )) ))
See GCM Advanced Topics for details on collapseKey, timeToLive, and delayWhileIdle.
- amazon()
- Amazon specific platform override payload.
$push->setNotification(P\notification( null, array("amazon"=>P\amazon( "Hello Amazon", null, null, null, null, array("articleid" => "AB1234") )) ))
See Amazon Device Messaging for details on consolidation_key and expires_after.
- blackberry()
- BlackBerry specific platform override payload.
$push->setNotification(P\notification( null, array("blackberry"=>P\blackberry( "Hello BlackBerry" )) ))
- wnsPayload()
- WNS specific platform override payload.
- mpnsPayload()
- MPNS specific platform override payload.
Device Types¶
In addition to specifying the audience, you must specify the device types you wish to target, either with a list of strings:
$push->setDeviceTypes(P\deviceTypes('ios', 'blackberry'));
or with the all shortcut.
$push->setDeviceTypes(P\all);
Rich Push¶
If you’d like to send a rich push along with your notification (or alone), use setMessage. See message() for more information about parameters.
$push->setMessage(P\message("This is the title",
"<html><body><h1>This is the message</h1></body></html>",
"text/html",
"utf-8",
0)
);
Note: Rich Push is not supported on Windows, Windows Phone, or Blackberry, and requires additional setup for other platforms. See our API and implementation docs for more information.