nsIPushSubscription

Includes information needed to send a push message to privileged code.
Inherits from: nsISupports Last changed in Gecko 46.0 (Firefox 46.0 / Thunderbird 46.0 / SeaMonkey 2.43)

Each subscription is associated with a unique URL generated by the Push service. Sending a POST request to this URL routes the message to the instance of Firefox that created the subscription. A subscription also has a public key and secret; these are used to encrypt message payloads.

This interface resembles PushSubscription from the Push API.

Method overview

void getKey(in DOMString name, [optional] out uint32_t keyLen, [array, size_is(keyLen), retval] out uint8_t key);
bool quotaApplies();
bool isExpired();

Attributes

Attribute Type Description
endpoint DOMString The subscription URL.
pushCount long long The total number of messages sent to this subscription.
lastPush long long The last time a message was sent to this subscription, in milliseconds since the epoch.
quota long The number of remaining background messages for this subscription, or -1 if exempt.

Methods

getKey()

Returns a byte array containing the key material for this subscription. The remote server can use these keys to encrypt and authenticate message payloads. The following key names are supported:

p256dh The ECDH public key, used as the input keying material in the HKDF invocation during encryption.
auth The shared authentication secret, used as the salt in the HKDF invocation. 
void getKey(
  in DOMString name,
  [optional] out uint32_t keyLen,
  [array, size_is(keyLen), retval] out uint8_t key
);

Parameters

name
The encryption key name.
keyLen
The keying material length.
key
The byte array containing the keying material.

keyLen and key are out parameters. When called from JavaScript, nsIPushSubscription.getKey() only takes name as a parameter, and returns key. Please see Method parameters in XPIDL for more details on using out parameters in JavaScript.

quotaApplies()

Indicates whether this subscription is subject to the background message quota.

bool quotaApplies();

nsIPushSubscription.quotaApplies() always returns false for system subscriptions.

Parameters

None.

isExpired()

Indicates whether this subscription has expired and must be renewed. A subscription expires if its service worker exceeds the quota, or if the desktop-notification permission for its origin is revoked.

bool isExpired();

nsIPushSubscription.isExpired() always returns false for system subscriptions.

Parameters

None.

Example

const { classes: Cc, interfaces: Ci, utils: Cu } = Components;

const scriptSecurityManager = Cc["@mozilla.org/scriptsecuritymanager;1"]
                                .getService(Ci.nsIScriptSecurityManager);
const pushService = Cc["@mozilla.org/push/Service;1"]
                      .getService(Ci.nsIPushService);

function sendSubscriptionToServer(subscription) {
  let request = Cc["@mozilla.org/xmlextras/xmlhttprequest;1"]
                  .createInstance(Ci.nsIXMLHttpRequest);
  request.open("POST", "https://example.com/register-for-push", true);
  request.addEventListener("error", () => {
    Cu.reportError("Error sending subscription to server");
  });
  request.send(JSON.stringify({
    endpoint: subscription.endpoint,

    // Base64-encode the key and authentication secret.
    key: String.fromCharCode.apply(null, btoa(subscription.getKey("p256dh"))),
    secret: String.fromCharCode.apply(null, btoa(subscription.getKey("auth"))),
  }));
}

pushService.subscribe(
  "chrome://my-module/push",
  scriptSecurityManager.getSystemPrincipal(),
  (code, subscription) => {
    if (!Components.isSuccessCode(code)) {
      Cu.reportError("Error creating subscription: " + code);
    } else {
      sendSubscriptionToServer(subscription);
    }
  }
);

See also