src/chrome/common/extensions/docs/templates/articles/gcm_server.html

   1 <meta name="doc-family" content="apps">
   2 <h1>API Reference for GCM service</h1>
   3
   4 <p>
   5 The <a href="cloudMessaging">Google Cloud Messaging for Chrome</a> service
   6 sends messages to users of a Chrome App.
   7 The service handles all aspects of queueing and delivering messages.
   8 To use the service,
   9 you must agree to the
  10 <a href="gcm_tos">Google Cloud Messaging for Chrome API Terms of Service</a>.
  11 </p>
  12
  13 <p>Messages must conform to these constraints:</p>
  14
  15 <ul>
  16         <li><strong>Maximum payload length:</strong> 256 bytes</li>
  17         <li><strong>Maximum subchannels:</strong> 4</li>
  18         <li><strong>Maximum API requests per day:</strong> 10,000</li>
  19 </ul>
  20
  21 <h2 id="libraries">Google API client libraries</h2>
  22
  23 <p>
  24 You may use the REST interface defined here
  25 to access Google Cloud Messaging for Chrome from your application.
  26 We also offer Google API client libraries for a number
  27 of popular programming languages that can be used to access the API.
  28 For more information, see
  29 <a href="https://developers.google.com/api-client-library">Google APIs Client Libraries</a>.
  30 </p>
  31
  32 <h2 id="insert">Insert method</h2>
  33
  34 <p>
  35 The <code>gcm_for_chrome.messages.insert</code>
  36 method sends a message to your app or extension user.
  37 </p>
  38
  39 <h2 id="authorization">Authentication</h2>
  40
  41 <p>
  42 Authentication is required to send messages to users.
  43 <a href="https://developers.google.com/accounts/docs/OAuth2WebServer">Using OAuth 2.0 for Web Server Applications</a>
  44 describes this in greater detail.
  45 </p>
  46
  47 <h3 id="url">URL</h3>
  48
  49 <p>
  50 The URL used to obtain access to the GCM for Chrome service:
  51 <code>https://accounts.google.com/o/auth2/auth</code>.
  52 </p>
  53
  54 <h3 id="parameters">Required parameters</h3>
  55 <p>
  56 The required set of query string parameters are:
  57 </p>
  58
  59 <table>
  60   <tr>
  61     <th scope="col">Parameter</th>
  62     <th scope="col">Description</th>
  63   </tr>
  64   <tr>
  65     <td><code>client_id</code></td>
  66     <td>Indicates the app or extension client that is making the request.
  67     Obtained from the <a href="https://code.google.com/apis/console/">Google APIs Console</a>;
  68     the parameter value must exactly match the client ID shown
  69     in the console.
  70     </td>
  71   </tr>
  72   <tr>
  73     <td><code>client_secret</code></td>
  74     <td>The client secret obtained during registration in
  75         <a href="https://code.google.com/apis/console/">Google APIs Console</a>.</td>
  76   </tr>
  77   <tr>
  78     <td><code>refresh_token</code></td>
  79     <td>Token associated with app or extension used to obtain new access token.</td>
  80   </tr>
  81   <tr>
  82     <td><code>grant_type</code></td>
  83     <td>The <code>authorization_code</code> value of <code>refresh_token</code>.</td>
  84   </tr>
  85 </table>
  86
  87 <h3 id="response">Response</h3>
  88
  89 <p>
  90 The authorization response includes:
  91 </p>
  92
  93 <table>
  94   <tr>
  95     <th scope="col">Field</th>
  96     <th scope="col">Description</th>
  97   </tr>
  98   <tr>
  99     <td><code>access_token</code></td>
 100     <td>Valid token required to access the GCM for Chrome service.</td>
 101   </tr>
 102   <tr>
 103     <td><code>expires_in</code></td>
 104     <td>Time until access token expires in seconds.</td>
 105   </tr>
 106   <tr>
 107     <td><code>token_type</code></td>
 108     <td>The returned token type, <code>Bearer</code>.</td>
 109   </tr>
 110 </table>
 111
 112 <h2 id="request">Message request</h2>
 113
 114 <h3 id="http">HTTP request</h3>
 115
 116 <p><code>POST https://www.googleapis.com/gcm_for_chrome/v1/messages</code></p>
 117
 118 <h3 id="body">Request body</h3>
 119
 120 <p>
 121 In the request body, supply:
 122 </p>
 123
 124 <table>
 125   <tr>
 126     <th scope="col">Parameter</th>
 127     <th scope="col">Description</th>
 128   </tr>
 129   <tr>
 130     <td><code>Content-Type</code></td>
 131     <td>The request body content type, <code>application/json</code>.</td>
 132   </tr>
 133   <tr>
 134     <td><code>Authorization</code></td>
 135     <td><code>Bearer</code> HTTP header including access token, for example,
 136     <code>Bearer 1/fFBGRNJru1FQd44AzqT3Zg</code>.</td>
 137   </tr>
 138   <tr>
 139     <td><code>channelId</code></td>
 140     <td>The app or extension channel ID required to push messages back to the app or extension.</td>
 141   </tr>
 142   <tr>
 143     <td><code>subchannelId</code></td>
 144     <td>The subchannel to send the message on; only values 0-3 are valid.</td>
 145   </tr>
 146   <tr>
 147     <td><code>payload</code></td>
 148     <td>The message body (up to 256 bytes). This should not include any
 149       personally identifiable information.</td>
 150   </tr>
 151 </table>
 152
 153 <p class="backtotop"><a href="#top">Back to top</a></p>