Merge pull request #626 from akeneo/quick-start-apps

meganelepalud-akeneo · web-flow · commit 1037a7850478 · 2022-08-05T10:47:02.000+02:00
Quick start apps
diff --git a/content/apps/apps-getting-started.md b/content/apps/apps-getting-started.md
@@ -1,77 +1,4 @@
-# Getting started
-
-## Overview
-
-Before you start planning and developing your App, it's essential to understand what Akeneo apps do and how they fit into Akeneo PIM.
-
-### What's an Akeneo app?
-
-An Akeneo App connects Akeneo PIM with third-party solutions. They can be easily connected directly from within PIM, with a streamlined process of activation and configuration.
-
-Most Akeneo apps are built by third-party developers, not by Akeneo.
-
-You can build an app to pull Akeneo data into your App to adapt and distribute it to external services, like e-commerce platforms or marketplaces. You can also push data to enrich the Akeneo PIM with translations, ERP data, assets, data pool content, or other sources.
-
-To tailor experiences to their specific needs, Akeneo users connect Akeneo apps to integrate with external services and improve how they collect, enrich and distribute their data.
-
-<img class="img-responsive in-article" alt="What's an app schema" src="../img/apps/whats-an-app.png" style="width: 500px;">
-
-
-### How apps fit into Akeneo PXM Studio?
-
-Apps integrate with Akeneo in the following ways:
-
-- using OAuth2.0 protocol to connect with Akeneo
-- using app catalogs to provide a consistent experience to users
-- connecting with our REST API to read and write Akeneo data
-
-![App in Akeneo PXM Studio](../img/apps/apps-fit-akeneo.png)
-
-::: info
-For more information on Apps usage, please read our help center articles
-[How to connect Akeneo PIM with third parties](https://help.akeneo.com/pim/serenity/articles/how-to-connect-my-pim-with-apps.html)
-and [Manage your Apps](https://help.akeneo.com/pim/serenity/articles/manage-your-apps.html).
-::::
-
-
-### Why apps over connectors?
-
-Both connectors and Apps use the OAuth standard. However, there are some significant differences.
-
-**AUTOMATIC CONFIGURATION INSTEAD OF MANUAL CONFIGURATION**
-
-***Connectors use Akeneo PIM connections to get credentials***
-
-The user who connects Akeneo PIM with a connector must create a connection and manually configure authorizations and permissions. Then, they copy/paste generated API credentials from the PIM UI to the connector. 
-
-***Apps use the Connect feature***
-
-When a user connects Akeneo PIM with an App, they click on Connect then follow the step-by-step activation process to accept requested authorizations and set up permissions. The App receives everything it needs to interact with Akeneo PIM at the end of this process. No more manual configuration issues and more transparency!
-
-**HIGH VISIBILITY**
-
-We give your App high visibility when you publish an App on the [Akeneo App Store](https://apps.akeneo.com/). Your App is displayed ***above all connectors***. We also give high visibility to Apps to our Akeneo PIM users. To do so, we created a ***dedicated section*** to highlight them in the PIM App Store.
-
-![PIM App Store](../img/apps/pim-marketplace-with-apps.png)
-
-
-**THIS IS JUST THE BEGINNING!**
-
-Akeneo promotes Apps and will communicate about new Apps published on the Akeneo App Store.
-
-Akeneo teams are also investing in Apps by developing new features for you to ease and accelerate App development and publication in the coming years. 
-
-And we are going to need your input so get ready to hear about us! 🎙️
-
-### Next steps
-
-- Learn how to [create an app](/apps/apps-getting-started.html#create-an-app)
-- Read our documentation about [authorization and authentication](/apps/authentication-and-authorization.html)
-- Learn how to use [catalogs](/apps/catalogs.html) to retrieve product data
-
-<!------------------------------ end of the Overview ------------------------------------>
-
-## Create an app
+# Create an app
 
 You're ready to create a new app. You want to set up your development environment so that you can start coding.
 
@@ -83,7 +10,7 @@ At the end of this tutorial, your App will receive an Access Token and will be a
 Please go to our [REST API Reference page](/api-reference-index.html) to learn more about our REST API endpoints. And if you want to know more about response codes, pagination, filters, or get troubleshooting information, go to the REST API basics page.
 :::
 
-### What you will learn
+## What you will learn
 In this tutorial, we provide a guide on how to implement the required parts of your App for the activation process based on OAuth 2.0 with Authorization Code.
 At the end of this tutorial, your App will receive an Access Token and will be able to call the REST API of a PXM Studio.
 
@@ -93,15 +20,15 @@ We strongly encourage you to adapt those examples with the framework or library
 :::
 
 ::: tips
-Reminder: our documentation is [open-source](https://github.com/akeneo/pim-api-docs).  
+Reminder: our documentation is [open-sourced](https://github.com/akeneo/pim-api-docs).  
 Feel free to contribute with languages we're not experts at.
 :::
 
-### Requirements
-- You have a [Partner account](https://www.akeneo.com/technology-partners/) and a developer sandbox [contact us](https://www.akeneo.com/contact/)
+## Requirements
+- You have your [App developer starter kit](/apps/overview.html#app-developer-starter-kit)
 - You understand [what's an Akeneo App](/apps/apps-getting-started.html#whats-an-akeneo-app) and [how they fit into Akeneo PXM Studio](/apps/apps-getting-started.html#how-apps-fit-into-akeneo-pxm-studio)
 
-### Step 1: Expose your activation and callback URLs
+## Step 1: Expose your activation and callback URLs
 
 First, your application must expose an **activation URL**.
 
@@ -125,13 +52,13 @@ You can find more information about the authorization process and code challenge
 - [What's the code challenge?](/apps/authentication-and-authorization.html#whats-the-code-challenge)
 :::
 
-### Step 2: Get a public URL for your in development App
+## Step 2: Get a public URL for your in development App
 
 Before proceeding to step 4 create a test App in your developer sandbox, you will need valid URLs to your App. This can be easily resolved with a tunnel to your localhost.
 
 There are several ways to create a tunnel to your localhost such as **localhost.run** or **ngrok**. We will use [localhost.run](https://localhost.run/) for its free and easy setup.
 
-#### Initiate localhost tunnel
+### Initiate localhost tunnel
 
 Initiate localhost tunnel using the following command:
 
@@ -143,7 +70,7 @@ ssh -R 80:localhost:8080 localhost.run
 The command above assumes that your local App is available on port 8080 but you can specify any port you want.
 
 
-#### Extract URL from the output
+### Extract URL from the output
 
 If everything goes well the command will output your public URL for your local app:
 
@@ -154,7 +81,7 @@ If everything goes well the command will output your public URL for your local a
 
 Your local app is now available at `https://46672a93dd64.lhrtunnel.link`. You may now use it for your development.
 
-### Step 3: Get your test app credentials
+## Step 3: Get your test app credentials
 
 To get credentials for your app, you need to create a test app on your developer sandbox.
 
@@ -181,7 +108,7 @@ To do so, you need to:
 5. Don't forget to save your modifications
 
 
-### Step 4: Connect your test App and access its settings
+## Step 4: Connect your test App and access its settings
 
 ![Test app on the App Store](../img/apps/marketplace-with-test-app.png)
 
@@ -205,7 +132,7 @@ To know more about the step-by-step activation process, please read our article:
 [How to connect an App?](https://help.akeneo.com/pim/serenity/articles/how-to-connect-my-pim-with-apps.html#how-to-connect-an-app)
 :::
 
-### Step 5: Use your access token to call the API
+## Step 5: Use your access token to call the API
 
 At the end of this process, you receive the following response with an `access_token`:
 
@@ -219,10 +146,9 @@ At the end of this process, you receive the following response with an `access_t
 
 You can use this token to call the Akeneo PIM REST API.
 
-
-### Next steps
+## Next steps
 
 - Explore the [REST API reference](/api-reference-index.html)
 - Discover how to [synchronize product data with your app](/getting-started/synchronize-pim-products-6x/welcome.html)
 - Start building your app by populating data to test your app against, designing your user interface, and interacting with the Akeneo REST API so that your app stays in sync with changing data
-- Publish your app on the [Akeneo App Store](https://apps.akeneo.com/how-submit-extension-akeneo-app-store)
+- [Publish your app](/apps/overview.html#publish-your-app) on the [Akeneo App Store](https://apps.akeneo.com/how-submit-extension-akeneo-app-store)
diff --git a/content/apps/authentication-and-authorization.md b/content/apps/authentication-and-authorization.md
@@ -51,7 +51,7 @@ After you've completed this tutorial, you'll be able to authorize an app created
 
 ### Requirements
 
-- You have a [Partner account](https://www.akeneo.com/technology-partners/) and a developer sandbox [contact us](https://www.akeneo.com/contact/).
+- You have your [App developer starter kit](/apps/overview.html#app-developer-starter-kit)
 - You're familiar with the [OAuth 2.0 flow](/apps/authentication-and-authorization.html#oauth-20) in Akeneo
 
 ### Step 1: Generate API credentials
@@ -253,7 +253,7 @@ After you've completed this tutorial, you'll be able to authenticate users comin
 
 ### Requirements
 
-- You have a [Partner account](https://www.akeneo.com/technology-partners/) and a developer sandbox [contact us](https://www.akeneo.com/contact/).
+- You have your [App developer starter kit](/apps/overview.html#app-developer-starter-kit)
 - You're familiar with [OpenID connect](https://openid.net/connect/)
 - You're familiar with the [app authentication process](/apps/authentication-and-authorization.html#getting-started-with-oauth-20)
 
diff --git a/content/apps/catalogs.md b/content/apps/catalogs.md
@@ -46,8 +46,8 @@ After completing this tutorial, you'll be able to create and use catalogs to ret
 
 ### Requirements
 
-- You have a [Partner account](https://www.akeneo.com/technology-partners/) and a developer sandbox [contact us](https://www.akeneo.com/contact/).
-- Your app already manages the authorization process.
+- You have your [App developer starter kit](/apps/overview.html#app-developer-starter-kit)
+- Your app already manages the authorization process
 
 ### Step 1: Ask for catalog scopes
 
diff --git a/content/apps/overview.md b/content/apps/overview.md
@@ -0,0 +1,82 @@
+# Overview
+
+Before you start planning and developing your app, it's essential to understand what Akeneo apps do and how they fit into Akeneo PIM.
+
+## What's an Akeneo app?
+
+An Akeneo App connects Akeneo PIM with third-party solutions. They can be easily connected directly from within PIM, with a **streamlined process of activation and configuration**.
+
+Most Akeneo apps are built by third-party developers, not by Akeneo.
+
+You can build an app to pull Akeneo data into your App to adapt and distribute it to external services, like e-commerce platforms or marketplaces. You can also push data to enrich the Akeneo PIM with translations, ERP data, assets, data pool content, or other sources.
+
+To tailor experiences to their specific needs, Akeneo users connect Akeneo apps to integrate with external services and improve how they collect, enrich and distribute their data.
+
+<img class="img-responsive in-article" alt="What's an app schema" src="../img/apps/whats-an-app.png" style="width: 500px;">
+
+::: tips 
+Want to know more about apps?  
+Discover the [Akeneo App Store and apps fundamentals course](https://akademy.akeneo.com/akeneo-app-store-apps-fundamentals) through our [Akeneo Academy](https://akademy.akeneo.com/).
+:::
+
+## How apps fit into Akeneo PXM Studio?
+
+Apps integrate with Akeneo in the following ways:
+
+- using **OAuth2.0 protocol** to connect with Akeneo
+- using app catalogs to provide a **consistent experience** to users
+- connecting with our **REST API** to read and write Akeneo data
+
+![App in Akeneo PXM Studio](../img/apps/apps-fit-akeneo.png)
+
+::: info
+For more information on apps usage, please read our help center articles
+[How to connect Akeneo PIM with third parties](https://help.akeneo.com/pim/serenity/articles/how-to-connect-my-pim-with-apps.html)
+and [Manage your apps](https://help.akeneo.com/pim/serenity/articles/manage-your-apps.html).
+::::
+
+
+## Why apps over connectors?
+
+Both connectors and apps are SaaS compatible and use API.  
+However, there are some significant differences.
+
+- **Automatic configuration instead of manual configuration**: connectors use Akeneo PIM connections to get credentials, apps use the OAuth 2.0. When a user connects Akeneo PIM with an app, they click on Connect then follow the step-by-step activation process to accept requested authorizations and set up permissions. The app receives everything it needs to interact with Akeneo PIM at the end of this process.  No more manual configuration issues and more transparency!
+- **High visibility**: we give your app high visibility when you publish an app on the [Akeneo App Store](https://apps.akeneo.com/). Your app is displayed ***above all connectors***. We also give high visibility to apps to our Akeneo PIM users. To do so, we created a ***dedicated section*** to highlight them in the Akeneo PXM Studio embedded App Store.
+- **Greater level of support**: we provide support to app developers to help them design, build, and test their app before publishing it on [Akeneo App Store](https://apps.akeneo.com/).
+- **Increase co-marketing opportunities**: Akeneo promotes apps and will communicate about new apps published on the Akeneo App Store, especially about certified apps. 
+- **Benefit from all the future features & improvements**: Akeneo teams are also investing in apps by developing new features for you to ease and accelerate app development and publication in the coming years. 
+
+![PIM App Store](../img/apps/pim-marketplace-with-apps.png)
+
+::: info 
+Want to know more about the app certification? [Contact us](https://www.akeneo.com/contact/). 
+:::
+
+
+## App developer starter kit
+
+Before starting to develop your app, we advise you to: 
+- Learn [how users connect their PIM with apps](https://help.akeneo.com/pim/serenity/articles/how-to-connect-my-pim-with-apps.html) and [how they manage their connected apps](https://help.akeneo.com/pim/serenity/articles/manage-your-apps.html)
+- Read our [guides](https://api.akeneo.com/guides-index.html) to better understand Akeneo and be aware of best pratices
+- Check our REST API [Reference](https://api.akeneo.com/api-reference-index.html) & [basics](https://api.akeneo.com/documentation/introduction.html)
+- Use our [developer tools](https://api.akeneo.com/apps/app-developer-tools.html)
+
+Then, you can [contact us](https://www.akeneo.com/contact/) to get your **App developer starter kit**: 
+- A developer sandbox with our [Serenity Enterprise version](https://help.akeneo.com/pim/serenity/versions-in-detail.html)
+- An access to our [support portal](https://apps-support.akeneo.com/) to easily ask questions, send suggestions or report a bug
+
+## Publish your app
+
+Your app is good to go? 
+
+- Discover our [extension approval requirements](https://apps.akeneo.com/extensions-approval-requirements)
+- [Contact us](https://www.akeneo.com/contact/) to demonstrate your app
+- Read our [how to publish your app](https://apps.akeneo.com/how-submit-extension-akeneo-app-store) guide
+- Consult our recommendations about [how to write your app information](https://apps.akeneo.com/how-write-akeneo-app-store-extension-information)
+
+## Next steps
+
+- Learn more about how to [create an app](/apps/apps-getting-started.html#create-an-app)
+- Read our documentation about [authorization and authentication](/apps/authentication-and-authorization.html)
+- Learn how to use [catalogs](/apps/catalogs.html) to retrieve product data
diff --git a/content/img/apps/pim-marketplace-with-apps.png b/content/img/apps/pim-marketplace-with-apps.png
diff --git a/src/partials/layout.handlebars b/src/partials/layout.handlebars
@@ -42,6 +42,9 @@
 
         <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
             <ul class="nav navbar-nav navbar-right">
+                <li class="{{#if active_apps}}active{{/if}}">
+                    <a href="/apps/overview.html">Apps</a>
+                </li>
                 <li class="{{#if active_guides}}active{{/if}}">
                     <a href="/guides-index.html">Guides</a>
                 </li>
@@ -53,7 +56,6 @@
                         <li><a href="/documentation/introduction.html">The REST API basics</a></li>
                         <li><a href="/events-documentation/overview.html">The Events API basics</a></li>
                         <li><a href="/php-client/introduction.html">The PHP API client</a></li>
-                        <li><a href="/apps/apps-getting-started.html">Apps</a></li>
                     </ul>
                 </li>
                 <li class="dropdown{{#if active_api_reference}} active{{/if}}">
diff --git a/tasks/build-doc.js b/tasks/build-doc.js
@@ -577,7 +577,8 @@ gulp.task('build-events-api', ['clean-dist','less'], function () {
 
 gulp.task('build-apps', ['clean-dist','less'], function () {
     var pages = {
-        'apps-getting-started.md': 'Getting started',
+        'overview.md': 'Overview',
+        'apps-getting-started.md': 'Create an app',
         'authentication-and-authorization.md': 'Authentication and authorization',
         'catalogs.md': 'Catalogs for Apps (beta)',
         'app-developer-tools.md': 'Developer tools'
@@ -595,7 +596,7 @@ gulp.task('build-apps', ['clean-dist','less'], function () {
               .on('end', function () {
                   return gulp.src('src/partials/apps.handlebars')
                     .pipe(gulpHandlebars({
-                        active_documentation:  true,
+                        active_apps:  true,
                         title: 'Apps',
                         mainContent: fs.readFileSync('tmp/apps/' + path.basename(file.path).replace(/\.md/, '.html'))
                     }, {
