get_started.html

{{+bindTo:partials.standard_store_article}}

<h1>Tutorial: Licensing API</h1>

<p>
This tutorial walks you through
creating an app that uses the Chrome Web Store Licensing API.
You have many choices when implementing an app for the Chrome Web Store,
but this tutorial features a common use case:
a hosted app that's implemented in Java,
with the help of Google App Engine and the Eclipse IDE.
</p>

<p>
You should be able to follow this tutorial
even if you've never used Java, Google App Engine, or Eclipse.
You'll get more out of this tutorial if you
read the <a href="index.html">Overview</a> first.
</p>

<p class="note">
<b>Note</b>:
You only need to use the Licensing API
if you use Chrome Web Store Payments.
For information on other payment options, see
<a href="index.html#charging">Charging for your app</a> in the Overview.
</p>

<h2 id="step1"> Step 1: Get ready </h2>

<p>
Before you start,
make sure you're using the Dev channel version of Google Chrome,
and learn how to find the Chrome Developer Dashboard.
</p>

<ol>
  <li>
    <p>
    Subscribe to the Dev channel by
    following the instructions in 
    <a href="http://www.chromium.org/getting-involved/dev-channel">Early Access Release Channels</a>.
    </p>
  </li>

  <li>
    <p>
    Find the Chrome Developer Dashboard.
    Until the Chrome Web Store is public,
    you can get to the dashboard
    from the Extensions Gallery.
    </p>
    <ol style="list-style-type: lower-alpha">
      <li> Go to the extensions management page,
        either by entering <b>chrome://extensions</b>
        in the address bar
        or by choosing the <b>Tools > Extensions</b> menu item
        from the wrench menu.
        (On the Mac, go to the <b>Window</b> menu and choose <b>Tools</b>.)
      </li>
      <li> Go to the Extensions Gallery
        by clicking the <b>Get more extensions</b> or
        <b>browse the gallery</b> link
        on the extensions management page.
      </li>
      <li> On the left side,
        look for the <b>Publish your extensions</b> link.
        At the bottom of the page,
        look for the <b>Developer Dashboard</b> link.
        Clicking either one takes you to the dashboard.
      </li>
    </ol>
  </li>
</ol>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="upload"> Step 2: Upload app info to the dashboard </h2>

<p>
Before you can write code that uses the Licensing API,
you need to upload your app with the Chrome Developer Dashboard.
In this step, you'll create and upload a ZIP file
containing the first draft of a manifest for your app.
</p>

<ol>
  <li>
    <p>
    Create a directory to contain your app's manifest and,
    eventually, icons.
    </p>
  </li>

  <li>
    <p>
    In this directory, create a file named <code>manifest.json</code>
    and copy the following code into it:
    </p>

<pre>
{
  "name": "Hello License!",
  "description": "Try this awesome app",
  "version": "0.0.0.1",
  "app": {
    "urls": [
      "*://example.com/"
    ],
    "launch": {
      "web_url": "http://example.com/mine/"
    }
  }
}
</pre>

    <p class="note">
    <b>Note</b>:
    This manifest uses dummy data
    because you can always change it later.
    The important thing, for now, is to have correct formatting.
    For information about what the manifest for a hosted app
    should really contain,
    see <a href="https://developers.google.com/chrome/apps/docs/developers_guide">Hosted Apps</a>.
    </p>
  </li>

  <li>
    <p>
    Create a ZIP archive of
    the directory that contains <code>manifest.json</code>.
    </p>
  </li>

  <li>
    <p>
    Upload the ZIP file to the Chrome Developer Dashboard.
    </p>

    <ol style="list-style-type: lower-alpha">

      <li> Go to the <a href="{{ dashboardurl }}">Chrome Developer Dashboard</a>
        and sign in. </li>

      <li> Click the <b>Add new item</b> button. <br />
        If you've never uploaded an item before,
        you need to accept the developer agreement before going on. </li>
      <li> Click <b>Choose file</b>,
        navigate to your ZIP file, and click <b>Upload</b>. </li>
    </ol>

    <p>
    Within seconds you should see an edit page for your app.
    At the top, you'll see a warning
    that you must verify ownership for example.com.
    Ignore it.
    You can update the manifest and verify ownership of your site later.
    </p>
  </li>

  <li>
    <p>
    At the bottom of the edit page,
    click <b>Save draft and return to dashboard</b>.
    You'll return to the Chrome Developer Dashboard,
    which lists installable web apps,
    extensions,
    and themes that you've uploaded.
    </p>
  </li>

  <li>
    <p>
    Go back to the edit page by
    clicking the <b>Edit</b> link for your app.
    </p>
  </li>

  <li>
    Get the app ID by inspecting the page's URL.
    <br />
    The URL in the browser's address bar
    should look something like this:

<pre>
https://chrome.google.com/extensions/developer/edit/abcdefghijklmnopqrstuvwxyzabcdef
</pre>

  <p>
  That long string of gibberish&mdash;abcdefghijklmnopqrstuvwxyzabcdef,
  in this example&mdash;is your app's ID.
  Save it, so you can use it in your code.
  </p>
  </li>
</ol>

<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="oauth"> Step 3: Get the OAuth token </h2>

<p>
In this step, you get the OAuth access token and access token secret
that allow you to use the Licensing API.
To get these, you first need to tell the store
that your app will use Chrome Web Store Payments.
</p>

<ol>
  <li>
    In the edit page for your app,
    click the <b>Change pricing</b> button.
  </li>

  <li>
    Choose <b>This application uses Chrome Web Store Payments</b>,
    and save.
  </li>

  <li>
    Return to the Chrome Developer Dashboard,
    and click the <b>OAuth setup</b> link
    for your app.

    <p class="note">
    <b>Note</b>:
    The OAuth setup link appears
    <em>only</em> if you've set the pricing of your app
    to use Chrome Web Store Payments.
    </p>

    A page comes up with information about the Licensing API
    and its use of OAuth.
  </li>

  <li>
    Click the <b>Generate new token</b> button
    at the bottom of the OAuth page.

    <p>
    <img src="images/oauthBoxBefore-gs.png"
      width="456" height="66"
      style="border:1px solid;"
      alt="A screenshot showing the bottom of the OAuth page before generating the new token" />
    </p>
  </li>

  <li>
    Save the values that appear next to
    <b>oauth_token_secret</b> and
    <b>oauth_token</b>. <br />
</pre>

    <p>
    <img src="images/oauthBoxAfter-gs.png"
      width="456" height="58"
      style="border:1px solid;"
      alt="A screenshot showing the generated token and secret at bottom of the OAuth page" />
    </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 secret,
you'll need to generate them again.
</p>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="prepare"> Step 4: Set up your development environment </h2>

<p>
Now that you have the IDs and tokens you need,
it's time to code.
But first,
you need to set up your development environment.
</p>

<p class="note">
<b>Note</b>:
This tutorial uses Google App Engine,
but you can use whatever technologies you like
when you create your own apps.
</p>

<ol>
  <li> Sign into
    <a href="https://appengine.google.com/">Google App Engine</a>,
    and create an application with the following information:
    <ul>
      <li> Identifier: Any unique identifier that makes sense to you.
        This identifier is used in the default app location;
        for example, choosing "hellolicense" results
        in a default app location of
        <a href="http://hellolicense.appspot.com">http://hellolicense.appspot.com</a> </li>
      <li> Title: Hello License! </li>
      <li> Authentication Options:
        Click the <b>Edit</b> link, and choose
        <b>Open to all users with an OpenID Provider</b>.
      </li>
    </ul>

    <p class="note"
    <b>Note</b>:
    If you've never used Google App Engine before,
    it will make you verify your account
    before you create an application.
    </p>

  </li>

  <li> Install the
    <a href="https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_for_Java">Google App Engine SDK for Java</a>.
  </li>

  <li> Install the <a href="http://www.eclipse.org/downloads/">Eclipse IDE for Java Developers</a>.
  </li>

  <li> Install the
    <a href="https://developers.google.com/eclipse/docs/download">Google Plugin for Eclipse</a>.
</ol>

<p>
For details see the
<a href="https://developers.google.com/appengine/docs/">Google App Engine documentation</a>, in particular
<a href="https://developers.google.com/appengine/docs/java/gettingstarted/">Getting Started: Java</a>.
</p>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="create"> Step 5: Create your app </h2>

<p>
In this step, you'll write your web app's code,
using the Eclipse IDE as your development environment.
</p>

<ol>
  <li>
    <p>
    In Eclipse, create a new web app project:
    <b>File > New > Web Application Project</b>.
    Name your project <b>HelloLicense</b>,
    set the package name to <b>com.example</b>,
    and uncheck the Google Web Toolkit option.
    Then click <b>Finish</b>.
    </p>
  </li>

  <li>
    <p>
    Get the following two JAR files,
    which are required by
    <a href="http://code.google.com/p/oauth-signpost/">OAuth Signpost</a>,
    the OAuth library that this example uses 
    to sign requests to the license server.
    </p>

    <dl>
      <dt> <code>signpost-core-1.2.1.1.jar</code> </dt>
      <dd> Download this file from
        <a href="http://code.google.com/p/oauth-signpost/downloads/list">http://code.google.com/p/oauth-signpost/downloads/list</a>. </dd>
      <dt> <code>commons-codec-1.4.jar</code> </dt>
      <dd> Download
        <code>commons-codec-1.4-bin.tar.gz</code> or
        <code>commons-codec-1.4-bin.zip</code> from
        <a href="http://commons.apache.org/codec/download_codec.cgi">http://commons.apache.org/codec/download_codec.cgi</a>,
        extract the files,
        and get <code>commons-codec-1.4.jar</code>
        from the top directory. </dd>
    </dl>

    <p>
    Put these two JAR files
    in your Eclipse project's
    <code>war/WEB-INF/lib</code> directory.
    </p>

  <li>
    <p>
    Now tell Eclipse about those JAR files.
    </p>

    <ol style="list-style-type: lower-alpha">
      <li> In Eclipse, refresh the display of your project.
        You can do this by opening a context menu in your project
        (such as by right-clicking your project's name in the Package Explorer)
        and choosing <b>Refresh</b>. </li>
      <li> Get to the Properties panel for your app.
        You can do this by opening a context menu again
        and choosing <b>Properties</b>. </li>
      <li> Go to the <b>Java Build Path</b> property list,
      choose the <b>Libraries</b> tab,
      and then click <b>Add JARs</b>. </li>
      <li> Navigate to the directory you just put the JAR files in,
        select the JAR files, and click <b>OK</b>. </li>
    </ol>
  </li>

  <li>
    <p>
    Copy the sample code to your main servlet.
    </p>

    <ol style="list-style-type: lower-alpha">
      <li> In the Project Explorer, go to
        <b>HelloLicense > src > com.example</b>,
        and double-click <b>HelloLicenseServlet.java</b>.</li>
      <li> Replace the contents of <b>HelloLicenseServlet.java</b>
        with the contents of
        <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/apps/hello-java/HelloLicenseServlet.java" target="_blank">this file</a>.
    </ol>

    <p>
      The code you paste in
      uses the Licensing API
      to check whether the user has access to this app.
      For code snippets and
      instructions on using the Licensing API, see
      <a href="check_for_payment.html">Checking for Payment</a>.
    </p>
  </li>

  <li>
    <p>
    In the code you just pasted in,
    fill in the APP_ID, TOKEN, and TOKEN_SECRET constants
    with the values you got in Steps 2 and 3.
    These constants are necessary for using the Licensing API.
    For example:
    </p>
<pre>
public static final String APP_ID = "abcdefghijklmnopqrstuvwxyzabcdef";
private static final String TOKEN = "1/knWSSAiX_-4o8abb-uSFk2_DaSrnpx9Y2udck-OuA7A";
private static final String TOKEN_SECRET = "t8KgYCxRv+0jNVY7DdrBQvto";
</pre>
  </li>

  <li>
    <p>
    Take a look at the code in <b>HelloLicenseServlet.java</b>:
    </p>
    <ul>
      <li>
        <p>
        The following lines get the OpenID URL for the user's
        Google Account,
        as described in
        <a href="identify_user.html">Identifying the User</a>.
        If you don't use Google App Engine,
        then instead of using UserService,
        you need to use an OpenID library
        and the Google OpenID endpoint.
        </p>
        
<pre>
UserService userService = UserServiceFactory.getUserService();
...
if (userService.isUserLoggedIn()) {
  User user = userService.getCurrentUser();
  <em>/* <b>user.getFederatedIdentity()</b> is the OpenID URL. */</em>
}
</pre>
      </li>

      <li>
        <p>
        The following code creates, signs, and sends a request
        to the license server,
        using the
        <a href="http://code.google.com/p/oauth-signpost/">OAuth Signpost library</a>
        and the standard
        <a href="http://download-llnw.oracle.com/javase/6/docs/api/java/net/URLConnection.html">URLConnection</a> class.
        The Licensing API URI in the request has the form
        https://www.googleapis.com/chromewebstore/v1/licenses/<em>appId</em>/<em>userId</em>.
        To sign the request,
        the OAuth library needs
        the app's access token and token secret,
        as well as the consumer key and secret (both "anonymous").
        </p>
<pre>
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>
      </li>

      <li>
        <p>
        The response from the license server is in JSON format,
        by default.
        The following code uses the
        <code>JSONObject.get</code> method to parse the response
        to figure out whether the user
        should have access to the app.
        If the "result" field value is "YES",
        then the user has either full or free trial access,
        depending on the value of the "accessLevel" field.
        </p>

<pre>
JSONObject json = new JSONObject(file);
output.printf(
  "Hello <strong>%s</strong> license!",
  "YES".equals(json.get("result")) ?
      "FULL".equals(json.get("accessLevel")) ? "full" : "free trial" :
      "no"
);
</pre>
        <p class="note">
        <b>Note</b>:
        Until users can buy apps, the value of the "result" field
        will always be "NO" unless you use a
        <a href="check_for_payment.html#testids-user">special test user ID</a>.
        </p>
      </li>
    </ul>
    </p>
  </li>
</ol>

<p>
For more information about using the Licensing API, see
<a href="check_for_payment.html">Checking for Payment</a>.
</p>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="deploy"> Step 6: Test and deploy your app </h2>

<p>
In this step, you'll make sure your app works,
and you'll deploy it to the web.
</p>

<ol>
  <li>
    <p>
      Still in Eclipse, choose <b>Run > Run As > Web Application</b>. <br />
      If it doesn't run, make sure you followed these instructions exactly,
      and try again.
      If it does run, you'll see the server location in the Eclipse Console.
    </p>
  </li>
  <li>
    <p>
      In a browser, visit the server location&mdash;for example,
      http://localhost:8888/&mdash;and
      click the link to <b>HelloLicense</b>. <br />
      You should see a simple page with a <b>Sign in</b> link.
    </p>
  </li>
  <li>
    <p>
      Sign in as text@example.com. <br />
      If you get an error page,
      then make sure you entered the app ID, OAuth access token, 
      and access token secret correctly.
    </p>

    <p class="note">
      <b>Note</b>:
      Currently, there's no way to pay,
      so you'll always be told that the user doesn't have access.
      However, in this developer release,
      you can modify the user ID that you supply
      so that you get a different answer.
      For details, see
      <a href="check_for_payment.html#testids-user">Special user IDs for testing</a>.
    </p>
  </li>

  <li>
    <p>
      Once you successfully run your app locally, deploy it:
      <ol style="list-style-type: lower-alpha">
        <li> Click the App Engine deploy button on the toolbar:
          <img src="images/ae_deploy_button.png"
            width="26" height="26" alt=""
            style="border:1px solid;" align="absmiddle" /> <br />
          A Deploy dialog comes up.
        </li>
        <li> Set the identifier to be used for Google App Engine.
          This is different from the Google Chrome app ID;
          it's the string you chose in
          <a href="#prepare">Step 4</a>.
          To set it, click the <b>App Engine project settings</b>
          link in the Deploy dialog,
          and then set the <b>Application ID</b> field
          to the string from Step 4&mdash;for example,
          "hellolicense".
        </li>
        <li>
          Click the <b>Deploy</b> button. <br />
          The Eclipse Console displays the status of the upload.
        </li>
      </ol>
    <li>
      <p>
        When your app is deployed,
        visit its new location under
        http://<em>identifier</em>.appspot.com.
        For an example, the app with the identifier "hellolicense" is at
        <a href="http://hellolicense.appspot.com/hellolicense">http://hellolicense.appspot.com/hellolicense</a>.
      </p>
    </li>
</ol>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="install"> Step 7: Install your app into Google Chrome </h2>

<p>
Once your website is up and running,
you can update the manifest and
test installing the app in Google Chrome.
This section won't lead you through that process in detail,
but here's a manifest for the Hello License app
that's served at http://hellolicense.appspot.com/hellolicense:
</p>

<pre>
{
  "name": "Hello License!",
  "description": "Try this awesome app",
  "version": "0.0.0.2",
  "app": {
    "urls": [
      "*://hellolicense.appspot.com/"
    ],
    "launch": {
      "web_url": "http://hellolicense.appspot.com/hellolicense"
    }
  },
  "icons": {
    "24": "icon_24.png",
    "128": "icon_128.png"
  }
}
</pre>

<p>
Note that you need to add icons
to the manifest and ZIP file,
so that your app can be installed.
Once you install this app,
the large icon appears in the New Tab page.
Clicking the icon takes you to 
http://hellolicense.appspot.com/hellolicense.
</p>

<p>
For details on manifest contents
and on installing an app that isn't yet packaged in a <code>.crx</code> file,
see 
<a href="https://developers.google.com/chrome/apps/docs/developers_guide">Hosted Apps</a>.
</p>


<p class="backtotop"><a href="#top">Back to top</a></p>
<h2 id="finish"> Step 8: Finish your app's listing </h2>

<p>
Use the edit page
to add all the store listing information
that isn't in the ZIP file,
such as a long description, screenshots, videos, and links to related sites.
You can preview what users will see for your app
by clicking the <b>Preview changes</b> button
at the bottom of the edit page.
</p>

<p>
For details on finishing and publishing an app, see
<a href="publish.html">Publishing Your App</a>.
</p>


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

<p>
Here are some choices for where to go next:
</p>

<dl>
  <dt> <a href="index.html">Overview</a> </dt>
  <dd> Get the conceptual background you need
    to use the Chrome Web Store well.
  </dd>

  <dt> <a href="check_for_payment.html">Checking for Payment</a> </dt>
  <dd> Learn how to use the Licensing API to
       check whether the user has paid for your app.
  </dd>

  <dt> <a href="samples.html">Samples</a> </dt>
  <dd> Find samples in multiple languages of hosted apps
       that use the Licensing API.
  </dd>

</dl>

<p>
If you just want to write your app,
see the developer doc for the type of app you're interested in:
</p>

<ul>
  <li> <a href="https://developers.google.com/chrome/apps/">Installable Web Apps</a> </li>
  <li> <a href="http://code.google.com/chrome/extensions/themes.html">Themes</a> </li>
  <li> <a href="http://code.google.com/chrome/extensions/index.html">Extensions</a> </li>
</ul>


<p class="backtotop"><a href="#top">Back to top</a></p>

{{/partials.standard_store_article}}