| blob | aefee4b3efe5eadbdb89064e1644a6ed5c50d991 |
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.
5 [
6 {
7 "namespace": "gcm",
8 "description": "Use <code>chrome.gcm</code> to enable apps and extensions to send and receive messages through the <a href='http://developer.android.com/google/gcm/'>Google Cloud Messaging Service</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='cloudMessaging#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": 86400,
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 86400 seconds (1 day)."
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 "from": {
132 "type": "string",
133 "optional": true,
134 "description": "The sender who issued the message."
135 },
136 "collapseKey": {
137 "type": "string",
138 "optional": true,
139 "description": "The collapse key of a message. See <a href='cloudMessaging#collapsible_messages'>Collapsible Messages</a> section of Cloud Messaging documentation for details."
140 }
141 }
142 }
143 ]
144 },
145 {
146 "name": "onMessagesDeleted",
147 "type": "function",
148 "description": "Fired when a GCM server had to delete messages sent by an app server to the application. See <a href='cloudMessaging#messages_deleted_event'>Messages deleted event</a> section of Cloud Messaging documentation for details on handling this event."
149 },
150 {
151 "name": "onSendError",
152 "type": "function",
153 "description": "Fired when it was not possible to send a message to the GCM server.",
154 "parameters": [
155 {
156 "name": "error",
157 "type": "object",
158 "description": "An error related to sending a message raised by GCM.",
159 "properties": {
160 "errorMessage": {
161 "type": "string",
162 "description": "The error message describing the problem."
163 },
164 "messageId": {
165 "type": "string",
166 "optional": true,
167 "description": "The ID of the message with this error, if error is related to a specific message."
168 },
169 "details": {
170 "type": "object",
171 "properties": {},
172 "additionalProperties": {
173 "type": "string"
174 },
175 "description": "Additional details related to the error, when available."
176 }
177 },
178 "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."
179 }
180 ]
181 }
182 ]
183 }
184 ]