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. <code>goog.</code> and <code>google</code> are disallowed as key prefixes. Sum of all key/value pairs should not exceed $ref: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 ] 162
