apns: github.com/anachronistic/apns Index | Files

package apns

import "github.com/anachronistic/apns"


Package Files

client.go client_mock.go feedback.go legacy.go mock_feedback_server.go push_notification.go push_notification_response.go


const FeedbackTimeoutSeconds = 5

Wait at most this many seconds for feedback data from Apple.

const IdentifierUbound = 9999

Every push notification gets a pseudo-unique identifier; this establishes the upper boundary for it. Apple will return this identifier if there is an issue sending your notification.

const MaxPayloadSizeBytes = 2048

Your total notification payload cannot exceed 2 KB.

const TimeoutSeconds = 5

The maximum number of seconds we're willing to wait for a response from the Apple Push Notification Service.


var (
    APPLE_PUSH_RESPONSES     = ApplePushResponses
    FEEDBACK_TIMEOUT_SECONDS = FeedbackTimeoutSeconds
    IDENTIFIER_UBOUND        = IdentifierUbound
    MAX_PAYLOAD_SIZE_BYTES   = MaxPayloadSizeBytes
    TIMEOUT_SECONDS          = TimeoutSeconds

These variables map old identifiers to their current format.

var ApplePushResponses = map[uint8]string{
    0:   "NO_ERRORS",
    3:   "MISSING_TOPIC",
    8:   "INVALID_TOKEN",
    10:  "SHUTDOWN",
    255: "UNKNOWN",

This enumerates the response codes that Apple defines for push notification attempts.

var FeedbackChannel = make(chan (*FeedbackResponse))

FeedbackChannel will receive individual responses from Apple.

var ShutdownChannel = make(chan bool)

If there's nothing to read, ShutdownChannel gets a true.

func StartMockFeedbackServer Uses

func StartMockFeedbackServer(certFile, keyFile string)

StartMockFeedbackServer spins up a simple stand-in for the Apple feedback service that can be used for testing purposes. Doesn't handle many errors, etc. Just for the sake of having something "live" to hit.

type APNSClient Uses

type APNSClient interface {
    ConnectAndWrite(resp *PushNotificationResponse, payload []byte) (err error)
    Send(pn *PushNotification) (resp *PushNotificationResponse)

APNSClient is an APNS client.

type AlertDictionary Uses

type AlertDictionary struct {
    Title        string   `json:"title,omitempty"`
    Body         string   `json:"body,omitempty"`
    TitleLocKey  string   `json:"title-loc-key,omitempty"`
    TitleLocArgs []string `json:"title-loc-args,omitempty"`
    ActionLocKey string   `json:"action-loc-key,omitempty"`
    LocKey       string   `json:"loc-key,omitempty"`
    LocArgs      []string `json:"loc-args,omitempty"`
    LaunchImage  string   `json:"launch-image,omitempty"`

AlertDictionary is a more complex notification payload.

From the APN docs: "Use the ... alert dictionary in general only if you absolutely need to." The AlertDictionary is suitable for specific localization needs.

func NewAlertDictionary Uses

func NewAlertDictionary() *AlertDictionary

NewAlertDictionary creates and returns an AlertDictionary structure.

type Client Uses

type Client struct {
    Gateway           string
    CertificateFile   string
    CertificateBase64 string
    KeyFile           string
    KeyBase64         string

Client contains the fields necessary to communicate with Apple, such as the gateway to use and your certificate contents.

You'll need to provide your own CertificateFile and KeyFile to send notifications. Ideally, you'll just set the CertificateFile and KeyFile fields to a location on drive where the certs can be loaded, but if you prefer you can use the CertificateBase64 and KeyBase64 fields to store the actual contents.

func BareClient Uses

func BareClient(gateway, certificateBase64, keyBase64 string) (c *Client)

BareClient can be used to set the contents of your certificate and key blocks manually.

func NewClient Uses

func NewClient(gateway, certificateFile, keyFile string) (c *Client)

NewClient assumes you'll be passing in paths that point to your certificate and key.

func (*Client) ConnectAndWrite Uses

func (client *Client) ConnectAndWrite(resp *PushNotificationResponse, payload []byte) (err error)

ConnectAndWrite establishes the connection to Apple and handles the transmission of your push notification, as well as waiting for a reply.

In lieu of a timeout (which would be available in Go 1.1) we use a timeout channel pattern instead. We start two goroutines, one of which just sleeps for TimeoutSeconds seconds, while the other waits for a response from the Apple servers.

Whichever channel puts data on first is the "winner". As such, it's possible to get a false positive if Apple takes a long time to respond. It's probably not a deal-breaker, but something to be aware of.

func (*Client) ListenForFeedback Uses

func (client *Client) ListenForFeedback() (err error)

ListenForFeedback connects to the Apple Feedback Service and checks for device tokens.

Feedback consists of device tokens that should not be sent to in the future; Apple *does* monitor that you respect this so you should be checking it ;)

func (*Client) Send Uses

func (client *Client) Send(pn *PushNotification) (resp *PushNotificationResponse)

Send connects to the APN service and sends your push notification. Remember that if the submission is successful, Apple won't reply.

type FeedbackResponse Uses

type FeedbackResponse struct {
    Timestamp   uint32
    DeviceToken string

FeedbackResponse represents a device token that Apple has indicated should not be sent to in the future.

func NewFeedbackResponse Uses

func NewFeedbackResponse() (resp *FeedbackResponse)

NewFeedbackResponse creates and returns a FeedbackResponse structure.

type MockClient Uses

type MockClient struct {

func (*MockClient) ConnectAndWrite Uses

func (m *MockClient) ConnectAndWrite(resp *PushNotificationResponse, payload []byte) (err error)

func (*MockClient) Send Uses

func (m *MockClient) Send(pn *PushNotification) (resp *PushNotificationResponse)

type Payload Uses

type Payload struct {
    Alert            interface{} `json:"alert,omitempty"`
    Badge            int         `json:"badge,omitempty"`
    Sound            string      `json:"sound,omitempty"`
    ContentAvailable int         `json:"content-available,omitempty"`
    Category         string      `json:"category,omitempty"`

Payload contains the notification data for your request.

Alert is an interface here because it supports either a string or a dictionary, represented within by an AlertDictionary struct.

func NewPayload Uses

func NewPayload() *Payload

NewPayload creates and returns a Payload structure.

type PushNotification Uses

type PushNotification struct {
    Identifier  int32
    Expiry      uint32
    DeviceToken string

    Priority uint8
    // contains filtered or unexported fields

PushNotification is the wrapper for the Payload. The length fields are computed in ToBytes() and aren't represented here.

func NewPushNotification Uses

func NewPushNotification() (pn *PushNotification)

NewPushNotification creates and returns a PushNotification structure. It also initializes the pseudo-random identifier.

func (*PushNotification) AddPayload Uses

func (pn *PushNotification) AddPayload(p *Payload)

AddPayload sets the "aps" payload section of the request. It also has a hack described within to deal with specific zero values.

func (*PushNotification) Get Uses

func (pn *PushNotification) Get(key string) interface{}

Get returns the value of a payload key, if it exists.

func (*PushNotification) PayloadJSON Uses

func (pn *PushNotification) PayloadJSON() ([]byte, error)

PayloadJSON returns the current payload in JSON format.

func (*PushNotification) PayloadString Uses

func (pn *PushNotification) PayloadString() (string, error)

PayloadString returns the current payload in string format.

func (*PushNotification) Set Uses

func (pn *PushNotification) Set(key string, value interface{})

Set defines the value of a payload key.

func (*PushNotification) ToBytes Uses

func (pn *PushNotification) ToBytes() ([]byte, error)

ToBytes returns a byte array of the complete PushNotification struct. This array is what should be transmitted to the APN Service.

type PushNotificationResponse Uses

type PushNotificationResponse struct {
    Success       bool
    AppleResponse string
    Error         error

PushNotificationResponse details what Apple had to say, if anything.

func NewPushNotificationResponse Uses

func NewPushNotificationResponse() (resp *PushNotificationResponse)

NewPushNotificationResponse creates and returns a new PushNotificationResponse structure; it defaults to being unsuccessful at first.

Package apns imports 13 packages (graph) and is imported by 32 packages. Updated 2018-02-21. Refresh now. Tools for package owners.