migrating.html

{{+bindTo:partials.standard_store_article}}

<h1>Migrating from a Packaged App to a Chrome App
    or Extension</h1>

<p>
    Since their initial introduction, packaged apps have evolved into
    Chrome Apps and Chrome Extensions. If your your legacy
    packaged app has an active user base, you will likely want to migrate to
    a new Chrome App or Extension, rather than publishing a new seperate item
    in the Chrome Web Store.
</p>

<h2 id="overview">Quick Overview of Migration</h2>

<ul>
    <li>You'll need to decide whether your new item should be either a Chrome
        App or a Chrome Extension.
    </li>

    <li>Convert your legacy app to the new type, test it, and package it as a
        ZIP file.
    </li>

    <li>In the CWS Developer Dashboard, upload the new ZIP.
    </li>
</ul>


<h2 id="step1">Step 1: Determine item type.</h2>

<p>First you'll need to determine the item type that best fits
    your application.</p>

<p>If your legacy app interacts with open-web content that your users browse
    to, expects to be in a Chrome tab, or needs a UI surface in the Chrome
    address bar, then it should become an extension. If, on the other hand,
    your legacy app is more like a native application and could be
    implemented as its own top-level window running side-by-side with Chrome
    rather than in a Chrome tab, then it should become a Chrome App.
</p>

<h2 id="step2">Step 2: Prepare for the new CWS</h2>

<p>You will also need to prepare for the new Chrome Web Store
    requirements.</p>
<p>
    The first requirement is that your manifest be updated to Version 2.
    Read the tutorial for migration to Manifest v2. In addition to certain
    manifest naming changes and the removal of certain deprecated APIs,
    Manifest Version 2 includes a default Content Security Policy. In the
    case of extensions, it's a good idea to update to CSP, but for Chrome
    Apps, it's a requirement.

    Finally, remove app:launch:local_path from your legacy app's manifest.
    This was the manifest key that determined that your app was a legacy
    packaged app. The next steps depend on which new item type you're
    targeting.
</p>


<h2 id="step3">Step 3: Update your
    code.
</h2>

<p>
    If you've decided your app should be a Chrome Extension, you'll want to
    familiarize yourself with all the details about Chrome Extensions.
    The principal difference between a legacy packaged app and a Chrome
    Extension is that packaged apps had their own Chrome tab to themselves,
    whereas extensions generally enhance other web content that your users
    are browsing in Chrome. So you'll need to decide whether to modify your
    legacy app to operate as an enhancement to web content, or else fit its
    UI into the surfaces offered by browser actions or page actions.
</p>

<p>
    If you've decided to convert your packaged app to a Chrome App, you'll
    need to understand the Chrome Apps lifecycle, and how to create an event
    page as the starting point for your app. The easiest first step will be
    to resurrect your legacy app in a Chrome App window. To do so, create an
    event page, and in the chrome.app.runtime.onLaunched() event handler,
    call chrome.app.window.create(), and for the url parameter, pass in the
    URL of the start page you had been using for app:launch:local_path in
    your legacy app manifest. Reloading your app should bring up a new
    window outside Chrome with your legacy app's content inside, and you can
    iterate from that point onward to restore any missing functionality.

    Once your app is running again, have a look at the new Chrome App APIs
    that are now available to your app. You might be inspired to take your
    legacy app in a whole new product direction!
</p>

<h2 id="step4">
    Step 4: Test your app
</h2>

<p>
    Some things to look out for: is user data preserved? Are all UI elements
    still reachable? If you're struggling to fit concepts from your app into
    the new type, consider whether you should change your app-or-extension
    decision.
</p>

<h2 id="step5">
    Step 5: Upload and Publish.
</h2>

<p>
    Once you upload the new version of your product, the Store will
    automatically detect that it's a new type.
</p>

<h2 id="step6">
    Step 6: Promote your new item
</h2>

<p>
    Congratulations! Your legacy app is now migrated. Let your users know
    about the change, and go find new users!
</p>


{{/partials.standard_store_article}}