src/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 for Android</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": "send",
  48         "type": "function",
  49         "description": "Sends a message according to its contents.",
  50         "parameters": [
  51           {
  52             "name": "message",
  53             "type": "object",
  54             "description": "A message to send to the other party via GCM.",
  55             "properties": {
  56               "destinationId": {
  57                 "type": "string",
  58                 "minLength": 1,
  59                 "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>."
  60               },
  61               "messageId": {
  62                 "type": "string",
  63                 "minLength": 1,
  64                 "description": "The ID of the message. It must be unique for each message."
  65               },
  66               "timeToLive": {
  67                 "type": "integer",
  68                 "minimum": 0,
  69                 "maximum": 2419200,
  70                 "optional": true,
  71                 "description": "Time-to-live of the message in seconds. If it is not possible to send the message wihtin that time an error 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)."
  72               },
  73               "data": {
  74                 "type": "object",
  75                 "properties": {},
  76                 "additionalProperties": {
  77                   "type": "string",
  78                   "minLength": 1
  79                 },
  80                 "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)."
  81               }
  82             }
  83           },
  84           {
  85             "name": "callback",
  86             "type": "function",
  87             "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.",
  88             "parameters": [
  89               {
  90                 "name": "messageId",
  91                 "type": "string",
  92                 "description": "The ID of the message that the callback was issued for."
  93               }
  94             ]
  95           }
  96         ]
  97       }
  98     ],
  99     "events": [
 100       {
 101         "name": "onMessage",
 102         "type": "function",
 103         "description": "Fired when a message is received through GCM.",
 104         "parameters": [
 105           {
 106             "name": "message",
 107             "type": "object",
 108             "description": "A message received from another party via GCM.",
 109             "properties": {
 110               "data": {
 111                 "type": "object",
 112                 "properties": {},
 113                 "additionalProperties": {
 114                   "type": "string"
 115                 },
 116                 "description": "The message data."
 117               }
 118             }
 119           }
 120         ]
 121       },
 122       {
 123         "name": "onMessagesDeleted",
 124         "type": "function",
 125         "description": "Fired when a GCM server had to delete messages to the application from its queue in order to manage its size. The app is expected to handle that case gracefully, e.g. by running a full sync with its server."
 126       },
 127       {
 128         "name": "onSendError",
 129         "type": "function",
 130         "description": "Fired when it was not possible to send a message to the GCM server.",
 131         "parameters": [
 132           {
 133             "name": "error",
 134             "type": "object",
 135             "description": "An error related to sending a message raised by GCM.",
 136             "properties": {
 137               "errorMessage": {
 138                 "type": "string",
 139                 "description": "The error message describing the problem."
 140               },
 141               "messageId": {
 142                 "type": "string",
 143                 "optional": true,
 144                 "description": "The ID of the message with this error, if error is related to a specific message."
 145               },
 146               "details": {
 147                 "type": "object",
 148                 "properties": {},
 149                 "additionalProperties": {
 150                   "type": "string"
 151                 },
 152                 "description": "Additional details related to the error, when available."
 153               }
 154             },
 155             "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."
 156           }
 157         ]
 158       }
 159     ]
 160   }
 161 ]