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