buford

README

Buford

Apple Push Notification (APN) Provider for Go 1.6 and HTTP/2.

Please see releases for updates.

Documentation

Buford uses Apple's new HTTP/2 Notification API that was announced at WWDC 2015 and released on December 17, 2015.

API documentation is available from GoDoc.

Also see Apple's Local and Remote Notification Programming Guide, especially the sections on the JSON payload and the Notification API.

Terminology

APN Apple Push Notification

Provider The Buford library is used to create a provider of push notifications.

Service Apple provides the push notification service that Buford communications with.

Client An http.Client provides an HTTP/2 client to communication with the APN Service.

Notification A payload sent to a device token with some headers.

Device Token An identifier for an application on a given device.

Payload The JSON sent to a device.

Headers HTTP/2 headers are used to set priority and expiration.

Installation

This library requires Go 1.6.2 or better.

Buford depends on several packages outside of the standard library, including the http2 package. Its certificate package depends on the pkcs12 and pushpackage depends on pkcs7. They can be retrieved or updated with:

go get -u golang.org/x/net/http2
go get -u golang.org/x/crypto/pkcs12
go get -u github.com/aai/gocrypto/pkcs7

I am still looking for feedback on the API so it may change. Please copy Buford and its dependencies into a vendor/ folder at the root of your project.

Examples

package main

import (
	"log"

	"github.com/RobotsAndPencils/buford/certificate"
	"github.com/RobotsAndPencils/buford/payload"
	"github.com/RobotsAndPencils/buford/payload/badge"
	"github.com/RobotsAndPencils/buford/push"
)

func main() {
	// set these variables appropriately
	filename := "/path/to/certificate.p12"
	password := ""
	deviceToken := "c2732227a1d8021cfaf781d71fb2f908c61f5861079a00954a5453f1d0281433"

	cert, err := certificate.Load(filename, password)
	if err != nil {
		log.Fatal(err)
	}

	service, err := push.NewService(push.Development, cert)
	if err != nil {
		log.Fatal(err)
	}

	p := payload.APS{
		Alert: payload.Alert{Body: "Hello HTTP/2"},
		Badge: badge.New(42),
	}

	id, err := service.Push(deviceToken, nil, p)
	if err != nil {
		log.Fatal(err)
	}
}

Headers

You can specify an ID, expiration, priority, and other parameters via the Headers struct.

headers := &push.Headers{
	ID:          "922D9F1F-B82E-B337-EDC9-DB4FC8527676",
	Expiration:  time.Now().Add(time.Hour),
	LowPriority: true,
}

id, err := service.Push(deviceToken, headers, p)

If no ID is specified APNS will generate and return a unique ID. When an expiration is specified, APNS will store and retry sending the notification until that time, otherwise APNS will not store or retry the notification. LowPriority should always be set when sending a ContentAvailable payload.

Custom values

To add custom values to an APS payload, use the Map method as follows:

p := payload.APS{
	Alert: payload.Alert{Body: "Message received from Bob"},
}
pm := p.Map()
pm["acme2"] = []string{"bang", "whiz"}

id, err := service.Push(deviceToken, nil, pm)

The Push method will use json.Marshal to serialize whatever you send it.

Resend the same payload

Use json.Marshal to serialize your payload once and then send it to multiple device tokens with PushBytes.

b, err := json.Marshal(p)
if err != nil {
	log.Fatal(err)
}

id, err := service.PushBytes(deviceToken, nil, b)

Whether you use Push or PushBytes, the underlying HTTP/2 connection to APNS will be reused.

Error responses

Push and PushBytes may return an error. It could be an error the JSON encoding or HTTP request, or it could be a push.Error which contains the response from Apple. To access the Reason and HTTP Status code, you must convert the error to a push.Error as follows:

if e, ok := err.(*push.Error); ok {
	switch e.Reason {
	case push.ErrBadDeviceToken:
		// handle error
	}
}

Website Push

Before you can send push notifications through Safari and the Notification Center, you must provide a push package, which is a signed zip file containing some JSON and icons.

Use pushpackage to write a zip to a http.ResponseWriter or to a file. It will create the manifest.json and signature files for you.

pkg := pushpackage.New(w)
pkg.EncodeJSON("website.json", website)
pkg.File("icon.iconset/icon_128x128@2x.png", "static/icon_128x128@2x.png")
// other icons... (required)
if err := pkg.Sign(cert, nil); err != nil {
	log.Fatal(err)
}

NOTE: The filenames added to the zip may contain forward slashes but not back slashes or drive letters.

See example/website/ and the Safari Push Notifications documentation.

Wallet (Passbook) Pass

A pass is a signed zip file with a .pkpass extension and a application/vnd.apple.pkpass MIME type. You can use pushpackage to write a .pkpass that contains a pass.json file.

See example/wallet/ and the Wallet Developer Guide.

Related Projects

• apns2 (Go)
• go-apns-server (Go mock server)
• Push Encryption (Go Web Push for Chrome and Firefox)
• Lowdown (Ruby)
• Apnotic (Ruby)
• Pigeon (Elixir, iOS and Android)

Documentation

Overview

Package buford is a Go 1.6+ HTTP/2 provider for Apple Push Notification Service (APNS).

Please see the README for usage.