chrome/common/extensions/api/gcm.json

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 [
   6   {
   7     "namespace": "gcm",
   8     "description": "Use <code>chrome.gcm</code> to enable apps and extensions to send and receive messages through <a href='http://developer.android.com/google/gcm/index.html'>Google Cloud Messaging</a>.",
   9     "properties": {
  10       "MAX_MESSAGE_SIZE": {
  11         "value": 4096,
  12         "description": "The maximum size (in bytes) of all key/value pairs in a message."
  13       }
  14     },
  15     "functions": [
  16       {
  17         "name": "register",
  18         "type": "function",
  19         "description": "Registers the application with GCM. The registration ID will be returned by the <code>callback</code>. If <code>register</code> is called again with the same list of <code>senderIds</code>, the same registration ID will be returned.",
  20         "parameters": [
  21           {
  22             "name": "senderIds",
  23             "type": "array",
  24             "items": {
  25               "type": "string",
  26               "minLength": 1
  27             },
  28             "minItems": 1,
  29             "maxItems": 100,
  30             "description": "A list of server IDs that are allowed to send messages to the application. It should contain at least one and no more than 100 sender IDs."
  31           },
  32           {
  33             "name": "callback",
  34             "type": "function",
  35             "description": "Function called when registration completes. It should check $(ref:runtime.lastError) for error when <code>registrationId</code> is empty.",
  36             "parameters": [
  37               {
  38                 "name": "registrationId",
  39                 "type": "string",
  40                 "description": "A registration ID assigned to the application by the GCM."
  41               }
  42             ]
  43           }
  44         ]
  45       },
  46       {
  47         "name": "unregister",
  48         "type": "function",
  49         "description": "Unregisters the application from GCM.",
  50         "parameters": [
  51           {
  52             "name": "callback",
  53             "type": "function",
  54             "description": "A function called after the unregistration completes. Unregistration was successful if $(ref:runtime.lastError) is not set.",
  55             "parameters": []
  56           }
  57         ]
  58       },
  59       {
  60         "name": "send",
  61         "type": "function",
  62         "description": "Sends a message according to its contents.",
  63         "parameters": [
  64           {
  65             "name": "message",
  66             "type": "object",
  67             "description": "A message to send to the other party via GCM.",
  68             "properties": {
  69               "destinationId": {
  70                 "type": "string",
  71                 "minLength": 1,
  72                 "description": "The ID of the server to send the message to as assigned by <a href='https://code.google.com/apis/console'>Google API Console</a>."
  73               },
  74               "messageId": {
  75                 "type": "string",
  76                 "minLength": 1,
  77                 "description": "The ID of the message. It must be unique for each message in scope of the applications. See the <a href='cloudMessagingV2#send_messages'>Cloud Messaging documentation</a> for advice for picking and handling an ID."
  78               },
  79               "timeToLive": {
  80                 "type": "integer",
  81                 "minimum": 0,
  82                 "maximum": 2419200,
  83                 "optional": true,
  84                 "description": "Time-to-live of the message in seconds. If it is not possible to send the message within that time, an onSendError event will be raised. A time-to-live of 0 indicates that the message should be sent immediately or fail if it's not possible. The maximum and a default value of time-to-live is 2419200 seconds (4 weeks)."
  85               },
  86               "data": {
  87                 "type": "object",
  88                 "properties": {},
  89                 "additionalProperties": {
  90                   "type": "string",
  91                   "minLength": 1
  92                 },
  93                 "description": "Message data to send to the server. Case-insensitive <code>goog.</code> and <code>google</code>, as well as case-sensitive <code>collapse_key</code> are disallowed as key prefixes. Sum of all key/value pairs should not exceed $(ref:gcm.MAX_MESSAGE_SIZE)."
  94               }
  95             }
  96           },
  97           {
  98             "name": "callback",
  99             "type": "function",
 100             "description": "A function called after the message is successfully queued for sending. $(ref:runtime.lastError) should be checked, to ensure a message was sent without problems.",
 101             "parameters": [
 102               {
 103                 "name": "messageId",
 104                 "type": "string",
 105                 "description": "The ID of the message that the callback was issued for."
 106               }
 107             ]
 108           }
 109         ]
 110       }
 111     ],
 112     "events": [
 113       {
 114         "name": "onMessage",
 115         "type": "function",
 116         "description": "Fired when a message is received through GCM.",
 117         "parameters": [
 118           {
 119             "name": "message",
 120             "type": "object",
 121             "description": "A message received from another party via GCM.",
 122             "properties": {
 123               "data": {
 124                 "type": "object",
 125                 "properties": {},
 126                 "additionalProperties": {
 127                   "type": "string"
 128                 },
 129                 "description": "The message data."
 130               },
 131               "collapseKey": {
 132                 "type": "string",
 133                 "optional": true,
 134                 "desctription": "The collapse key of a message. See <a href='cloudMessagingV2#collapsible_messages'>Collapsible Messages</a> section of Cloud Messaging documentation for details."
 135               }
 136             }
 137           }
 138         ]
 139       },
 140       {
 141         "name": "onMessagesDeleted",
 142         "type": "function",
 143         "description": "Fired when a GCM server had to delete messages sent by an app server to the application. See <a href='cloudMessagingV2#messages_deleted_event'>Messages deleted event</a> section of Cloud Messaging documentation for details on handling this event."
 144       },
 145       {
 146         "name": "onSendError",
 147         "type": "function",
 148         "description": "Fired when it was not possible to send a message to the GCM server.",
 149         "parameters": [
 150           {
 151             "name": "error",
 152             "type": "object",
 153             "description": "An error related to sending a message raised by GCM.",
 154             "properties": {
 155               "errorMessage": {
 156                 "type": "string",
 157                 "description": "The error message describing the problem."
 158               },
 159               "messageId": {
 160                 "type": "string",
 161                 "optional": true,
 162                 "description": "The ID of the message with this error, if error is related to a specific message."
 163               },
 164               "details": {
 165                 "type": "object",
 166                 "properties": {},
 167                 "additionalProperties": {
 168                   "type": "string"
 169                 },
 170                 "description": "Additional details related to the error, when available."
 171               }
 172             },
 173             "description": "An error that occured while trying to send the message either in Chrome or on the GCM server. Application can retry sending the message with a reasonable backoff and possibly longer time-to-live."
 174           }
 175         ]
 176       }
 177     ]
 178   }
 179 ]