check_for_payment.html

{{+bindTo:partials.standard_store_article}}

<h1>Checking for License Payment</h1>

<p>
If you plan to use Chrome Web Store Payments,
you can use the Chrome Web Store Licensing API
to determine whether the user has paid.
The Licensing API is a simple REST-based API
that lets you query the Chrome Web Store license server
to find out whether a particular user
has paid for a particular app.
</p>

<p>
Generally, you use the Licensing API in hosted apps.
Although you can use the API in packaged apps and extensions,
it's more difficult for them to use the license server securely.
</p>

<p class="note">
<b>Note</b>:
This page applies only if you use Chrome Web Store Payments.
Chrome Web Store payment methods are not available for hosted apps.
For information on other options, see
<a href="https://developer.chrome.com/webstore/overview#charging">Charging for your app</a> in the Overview.
</p>

<p id="video">
<object width="400" height="250"><param name="movie" value="https://www.youtube.com/v/uGTm6_KbG-g?fs=1&amp;hl=en_US"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="https://www.youtube.com/v/uGTm6_KbG-g?fs=1&amp;hl=en_US" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="400" height="250"></embed></object>
</p>

<h2 id="overview">Overview of using the Licensing API</h2>

<p>
Using the Licensing API requires a user ID, an app ID,
and an OAuth access token and token secret.
The user ID is the OpenID URL
for the user's Google Account.
You can get the app ID and the OAuth access token and token secret
from the Chrome Developer Dashboard
after you upload your app for the first time.
</p>

<p>
Here's an overview of the process of
writing code that uses the Licensing API:
</p>

<ul>
  <li> Get the app ID and OAuth access token from the Chrome Developer Dashboard. </li>
  <li> Add code to get the Google Account OpenID URL for the current user. </li>
  <li> Add code to make a signed OAuth request to the license server. </li>
  <li> Add code to handle the response from the license server. </li>
</ul>

<p>
Read the following sections for details about this process,
with tips on testing your code.
</p>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="setup"> Get access to the Licensing API </h2>

<p>
Before you can use the Licensing API for a particular app,
you need to do some one-time preparation:
</p>

<ol>
  <li>
    Upload a ZIP file for your app to the Chrome Developer Dashboard.
    See <a href="publish.html#step3">Step 3 in Publishing Your App</a> for details.
  </li>
  <li>
   In the edit page for your app,
   click the <b>Change pricing</b> button,
   choose <b>This application uses Chrome Web Store Payments</b>,
   and save.
  </li>
  <li>
    Get your app's ID,
    which you can do either as described in
    <a href="publish.html#step5">Step 5 of Publishing Your App</a>
    or when you get an OAuth access token.
  </li>
  <li>
    Get an OAuth access token and token secret
    so that your app can use the Licensing API.
    For details, see the next section.
  </li>
</ol>

<h3 id="token"> Getting an OAuth access token and token secret (hosted
    apps only)</h3>

<p>
For hosted apps, you can get the access token and access token secret for your
    app
from a special page in the Chrome Developer Dashboard.
Here's how.
</p>

<ol>
  <li>
    <p>
    Go to the
    <a href="https://chrome.google.com/webstore/developer/dashboard">Chrome Developer Dashboard</a>.
    As the following screenshot shows,
    each hosted app that you've uploaded
    and that uses Chrome Web Store Payments
    has an <b>OAuth setup</b> link
    that lets you get OAuth information for that app.
    </p>

    <p>
    <img src="images/dashboard.png"
      style="border:1px solid;"
      width="639" height="231"
      alt="The Developer Dashboard, with information about 3 apps of various types" />
    <br />
    <em>In this dashboard, two apps have an OAuth setup link</em>
    </p>

    <p class="note">
    <b>Note</b>: The <b>OAuth
        setup</b> link is only shown for hosted apps. If you don't see the
        <b>OAuth setup</b> link for your hosted app,
    click the <b>Edit</b> link
    and use the <b>Change pricing</b> button
    to specify that your app uses Chrome Web Store Payments.
    </p>
  </li>

  <li>
    <p>
      Click the <b>OAuth setup</b> link.
      You get a page with OAuth information
      for the Licensing API.
      At the bottom of that page is the information you need
      to make Licensing API requests with your app,
      including the app ID
      but <em>not</em>
      the access token and token secret.
      Here's an example of what you might see:
    </p>

    <p>
    <img src="images/oauthBoxBefore.png"
      style="border:1px solid;"
      width="540" height="250"
      alt="Miscellaneous OAuth-related information. The values for oauth_token_secret and oauth_token say 'Click button to generate'." />
    <br />
    <em>What the bottom of the OAuth window looks like before you generate a token</em>
    </p>
  </li>

  <li>
    <p>
      Click the <b>Generate new token</b> button
      at the bottom of the page to generate
      the OAuth access token and token secret for your app.
    </p>
    <p>
    <img src="images/oauthBoxAfter.png"
      style="border:1px solid;"
      width="562" height="250"
      alt="Same as above, but with string values for the oauth_token_secret and oauth_token" />
    <br />
    <em>What you see after generating a token</em>
    </p>
  </li>

  <li>
    <p>
      Record the token and token secret in a safe place.
      The dashboard will not show them to you again.
    </p>
  </li>
</ol>

<p class="warning">
<b>Important:</b>
Keep your access token and token secret safe and private.
(The screenshot shows sample values that won't work.)
If you lose the token or token secret,
you'll have to return to the dashboard and generate them again.
</p>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="request"> Make a signed OAuth request </h2>

<p>
To make a request with the Licensing API,
you need the following:
</p>

<ul>
  <li> a <b>user ID</b> for the current user
    (an OpenID URL corresponding to a Google account) </li>
  <li> the <b>app ID</b> for your app </li>
  <li> the <b>OAuth access token</b> that gives your app access to the Licensing API </li>
  <li> the corresponding <b>access token secret</b> </li>
  <li> a <b>consumer key</b> ("anonymous") </li>
  <li> a <b>consumer secret</b> ("anonymous") </li>
</ul>

<p>
All of these except the user ID are constant for your app.
When you have them all,
you can create and send a signed OAuth request to the licensing server,
signing it using the HMAC-SHA1 algorithm.
Here's the request you send
if you want the response in JSON format:
</p>

<pre>
https://www.googleapis.com/chromewebstore/v1/licenses/<em>appId</em>/<em>userID</em>
</pre>

<p>
If you want the response in ATOM format,
you add <code>?alt=atom</code> to the request:
</p>

<pre>
https://www.googleapis.com/chromewebstore/v1/licenses/<em>appId</em>/<em>userID</em>?alt=atom
</pre>

<p>
The next sections have further details on getting the user ID,
creating the request, and sending the request.
</p>


<h3 id="userid"> Get the user ID </h3>

<p>
The user ID is an OpenID URL
corresponding to a Google Account.
See <a href="identify_user.html">Identifying the user</a>
for instructions on getting the current user's ID using OpenID.
</p>


<h3 id="create"> Create, sign, and send the request </h3>

<p>
You should use an OAuth library to help create and sign the request.
The following Java example
creates, signs, and sends a request, using the
<a href="http://code.google.com/p/oauth-signpost/">OAuth Signpost library</a>
and the standard
<a href="https://docs.oracle.com/javase/7/docs/api/java/net/URLConnection.html">URLConnection</a> class.
</p>

<pre>
public static final String APP_ID = "<em>yourAppId</em>";
private static final String TOKEN = "<em>anOAuthToken</em>";
private static final String TOKEN_SECRET = "<em>anOAuthTokenSecret</em>";
public static final String SERVER_URL =
    "https://www.googleapis.com/chromewebstore/v1/licenses/%s/%s";
public static final String CONSUMER_KEY = "anonymous";
public static final String CONSUMER_SECRET = CONSUMER_KEY;
...
OAuthConsumer oauth = new DefaultOAuthConsumer(CONSUMER_KEY, CONSUMER_SECRET);
oauth.setTokenWithSecret(TOKEN, TOKEN_SECRET);
URLConnection http =
    new URL(
      String.format(
        SERVER_URL,
        APP_ID,
        URLEncoder.encode(user.getFederatedIdentity(), "UTF-8")
      )
    ).openConnection();
oauth.sign(http);
http.connect();
</pre>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="response"> Handle the response </h2>

<p>
The response you get from the license server tells you three things:
whether the user has access to the app,
the level of access the user should have,
and how much longer the response is valid.
If you just want to know whether the user has access,
check the value of the <code>result</code> field.
If you want to know whether the user should get
a free trial version of the app,
check the value of the <code>accessLevel</code> field.
(If you're using ATOM, the field name is all lowercase:
<code>accesslevel</code>.)
</p>

<p>
The response is valid for the number of seconds specified by the value of
the <code>maxAgeSecs</code> field.
Once that time has passed,
you should query the license server again
to check whether the user's access has changed.
</p>

<p class="note">
<b>Note</b>:
The <code>max-age</code> directive of the response's Cache-Control HTTP header
has the same value
as the <code>maxAgeSecs</code> field.
Use whichever one is most convenient.
</p>

<table>
<tr>
  <th>Situation</th> <th><code>result</code></th> <th><code>accessLevel</code></th>
</tr>
<tr>
  <td> The user has paid for the app. </td>
  <td> <code>YES</code> </td>
  <td> <code>FULL</code> </td>
</tr>
<tr>
  <td> The user hasn't paid for the app,
    but should get a free trial version.
  </td>
  <td> <code>YES</code> </td>
  <td> <code>FREE_TRIAL</code> </td>
</tr>
<tr>
  <td> The user has not paid for the app,
    and shouldn't have access to the app.
    <p class="note">
    <b>Note</b>:
    In this situation,
    your app should provide an easy way for the user to buy it,
    such as by providing a prominent link to its store listing.
    </p>
  </td>
  <td> <code>NO</code> </td>
  <td> <code>NONE</code> </td>
</tr>
</table>


<h3 id="parse"> Parse the JSON or ATOM data </h3>

<p>
Unless you specify otherwise,
you get a JSON response back from the license server.
Once unescaped,
it looks something like this:
</p>

<pre>
{
   "kind": "chromewebstore#license",
   "id": "<em>appId</em>/<em>userId</em>",
   "appId": "<em>appId</em>",
   "userId": "<em>userId</em>",
   "result": "YES",
   "accessLevel": "FULL",
   "maxAgeSecs": "3600",
}
</pre>

<p>
If your GET request has <code>?alt=atom</code>,
you get ATOM data,
which looks something like this
after unescaping:
</p>

<pre>
&lt;entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:gd="http://schemas.google.com/g/2005"
       xmlns:cws="http://schemas.google.com/chromewebstore/2010"
       gd:kind="chromewebstore#license">
    &lt;id>http://www.googleapis.com/chromewebstore/licenses/
<em>appId</em>/<em>userId</em>&lt;/id>
  &lt;cws:appid><em>appId</em>&lt;/cws:appid>
  &lt;cws:userid><em>userId</em>&lt;/cws:userid>
  &lt;cws:result>YES&lt;/cws:result>
  &lt;cws:accesslevel>FULL&lt;/cws:accesslevel>
  &lt;cws:maxAgeSecs>3600&lt;/cws:maxAgeSecs>
&lt;/entry>
</pre>

<p>
Use your favorite JSON or XML parser
to get the value of the fields you're interested in.
The following example checks
both the <code>result</code> and <code>accessLevel</code> fields
of a JSON-formatted response from the license server.
</p>

<pre>
JSONObject json = new JSONObject(body);
Object result = json.get("result");
String license = "no";

if (result != null && result.equals("YES")) {
  Object accessLevel = json.get("accessLevel");
  license = accessLevel != null && accessLevel.equals("FULL") ?
      "full" : "free-trial";
}
</pre>

<p>
For more code, see the
<a href="samples.html">Samples</a>.
</p>


<h3 id="cache"> Cache the results </h3>

<p>
To improve the performance of your app
and avoid running into rate limits,
don't make a license server request every time you load a resource.
Instead, make one request and then cache the results
for the number of seconds
specified by the <code>maxAgeSecs</code> field
(or by the <code>max-age</code> directive
of the Cache-Control HTTP header).
</p>

<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="test"> Test your implementation </h2>

<p>
While testing your app's interaction with the license server,
you can use the OAuth Playground
and special user IDs.
</p>


<h3 id="playground">The OAuth Playground</h3>

<p>
If you have difficulties with your license server requests or responses,
or if you just want to see for yourself
what the responses look like,
try the
<a href="http://googlecodesamples.com/oauth_playground/">OAuth Playground</a>.
The Playground lets you send raw API requests,
displaying the full request and the response returned by the server.
</p>

<p class="note">
<b>Note</b>:
When you use the OAuth Playground,
click the <b>execute</b> button to send the request.
Pressing Enter doesn't work.
</p>


<h3 id="testids-user"> Special user IDs for testing </h3>

<p>
Before releasing your app to the general public,
you should have a few trusted testers try out the
install/payment flow.
You can do this by creating a version of your app
that you publish only to a few accounts.
For details, see
<a href="publish.html#testaccounts">Publishing to test accounts</a>.
</p>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="resources"> OAuth resources </h2>

<p>
You should use an existing OAuth library rather than implement your own.
Here are a few libraries we've used:
</p>

<ul>
  <li> Java:
       <a href="http://code.google.com/p/oauth-signpost/">OAuth Signpost</a>
       </li>
  <li> Python:
       <a href="http://github.com/simplegeo/python-oauth2">Python OAuth2</a>
       </li>
  <li> PHP:
       <a href="http://oauth.googlecode.com/svn/code/php/">OAuth for PHP</a>
       </li>
  <li> Ruby:
       <a href="https://rubygems.org/gems/signet">Signet</a>
       </li>
</ul>

<p>
You can find more libraries at the
<a href="http://oauth.net/code/">OAuth Code page</a>.
</p>

<p>
For a detailed explanation of using OAuth, see
<a href="https://developers.google.com/accounts/">Authentication and Authorization for Google APIs</a>.
</p>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="next">What next?</h2>

<p>
Read <a href="images.html">Supplying Images</a>.
</p>

{{/partials.standard_store_article}}