diff --git a/src/data/navigation/sections/app-development.js b/src/data/navigation/sections/app-development.js index 05406c129..11de93539 100644 --- a/src/data/navigation/sections/app-development.js +++ b/src/data/navigation/sections/app-development.js @@ -21,6 +21,7 @@ module.exports = [ }, ] }, + /* { title: "Best practices", path: "/app-development/best-practices/index.md", @@ -39,28 +40,7 @@ module.exports = [ } ] }, - { - title: "Reference App", - path: "/app-development/amazon-sales-channel/index.md", - pages: [ - { - title: "Overview", - path: "/app-development/amazon-sales-channel/index.md", - }, - { - title: "Prerequisites", - path: "/app-development/amazon-sales-channel/prerequisites.md", - }, - { - title: "Installation", - path: "/app-development/amazon-sales-channel/installation.md", - }, - { - title: "Release Notes", - path: "/app-development/amazon-sales-channel/release-notes.md" - } - ] - }, + */ { title: "App submission guidelines", path: "/app-development/app-submission-guidelines.md" diff --git a/src/pages/app-development/amazon-sales-channel/index.md b/src/pages/app-development/amazon-sales-channel/index.md deleted file mode 100644 index 2240ed06d..000000000 --- a/src/pages/app-development/amazon-sales-channel/index.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Amazon Sales Channel on App Builder overview -description: Learn how you can use Amazon Sales Channel on App Builder as a reference app to build your own Adobe Commerce apps. -keywords: - - App Builder - - Extensibility ---- - -# Amazon Sales Channel on App Builder overview - -Amazon Sales Channel on App Builder is a flagship reference app developed by Adobe Commerce to accelerate merchant and partner adoption of out-of-process extensibility. - -This app showcases how Adobe Developer App Builder can create integrations and extensions without modifying the core Commerce application. [Amazon Sales Channel on App Builder](https://github.com/adobe/amazon-sales-channel-app-builder) focuses on demonstrating how to develop key capabilities and extensibility use cases with App Builder. Partners and developers can leverage the application code, best practice guides, and documentation to confidently create their own next-generation extensions and integrations. - -The application presents many common use cases for extending Adobe Commerce, including: - -* Integration with a 3rd-party system -* Product catalog synchronization -* UI extensibility - -Amazon Sales Channel on App Builder is based on an existing PHP extension (Amazon Sales Channel) that was internally developed by Adobe Commerce. This specific integration was chosen because of the breadth of the use cases required, the existing internal familiarity with connecting to Amazon, and the ability to directly compare how capabilities are implemented between the two free, publicly accessible applications. - - - -This app is not intended or supported for production use. While the provided capabilities are robust, they are only to be used as a reference to build your own applications. Merchants looking to connect and synchronize their Amazon store with Commerce should implement another integration. - -To install this app, clone the [aio-amazon-sales-channel](https://github.com/adobe/amazon-sales-channel-app-builder) repo and follow the procedures described in [Prequisites](prerequisites.md) and [Install the Amazon Sales Channel app](installation.md). - -## Application functionality - -Amazon Sales Channel on App Builder connects Adobe Commerce and Amazon to unify and synchronize your selling platforms. This type of integration allows merchants to manage their product and order data from a single, up-to-date experience. The sample app functionality represents only a subset of the original PHP extension's capabilities. We chose this subset of functionality based on the value provided to partners and developers looking to understand and use our next generation extensibility capabilities. - -The central goal of this reference app is to build confidence in the App Builder framework and deliver reusable, Commerce-specific patterns for accelerating implementations. - -## Merchant documentation - -You can use the [PHP extension user guide](https://experienceleague.adobe.com/docs/commerce-channels/amazon/guide-overview.html) to understand the reference app behaviors. Note that Amazon Sales Channel on App Builder does not feature order management, listing and pricing rules, and several other capabilities of the PHP application. - -In general, the sample app looks and feels like the PHP extension. However, some capabilities and behaviors are not exactly the same. Partners and developers should view Amazon Sales Channel on App Builder as a learning tool to enable building high-quality, out-of-process apps with confidence. - -## Additional resources - -* Join the [#app-builder-community slack channel](https://magentocommeng.slack.com/archives/C04KT43Q75K) in the Commerce Engineering Slack workspace to ask questions directly to teams and partners working with App Builder. - -* Review [Common Troubleshooting](https://developer.adobe.com/app-builder/docs/getting_started/common_troubleshooting/) in the App Builder _Getting Started_ guide for the latest debugging tips. diff --git a/src/pages/app-development/amazon-sales-channel/installation.md b/src/pages/app-development/amazon-sales-channel/installation.md deleted file mode 100644 index 60391e3a9..000000000 --- a/src/pages/app-development/amazon-sales-channel/installation.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: Install the Amazon Sales Channel app -description: Learn how to install the reference App Builder app for Adobe Commerce. -keywords: - - App Builder - - Extensibility ---- - -# Install the Amazon Sales Channel app - - - -Review the [Prerequisites](prerequisites.md) before you attempt to install the Amazon Sales Channel app. - -## Clone application source code - -Clone the [`amazon-sales-channel-app-builder` repo](https://github.com/adobe/amazon-sales-channel-app-builder) to your working directory: - -```bash -git clone git@github.com:adobe/amazon-sales-channel-app-builder.git -``` - -## Setup project dependencies - -Change directories to the cloned repo and run the following commands: - -1. Download dependencies and prepare the project. - - ```bash - npm install - ``` - -1. Build the project. - - ```bash - npm run build - ``` - - The command cleans, compiles, and runs the `aio app build` command. - -## Configure your application - -### Add services - -In your App Builder project: - -1. In your workspace, click the **Add service** pop-up menu and select **API**. - -1. On the **Add an API** page, filter on **Adobe Services** and select **I/O Management API**. Then click **Next**. - -1. On the **Configure API** page, select the **Service Account (JWT)** option and click **Save configured API**. - -1. Select **Generate key pair**. - -1. Click **Save configured API**. - -1. Repeat this process and create an `Adobe I/O Events for Adobe Commerce` service. - -### Set up your environment - -1. From the root of the cloned repo, make a copy of the `.env.dist` file. - - ```bash - cp .env.dist .env - ``` - -1. Run the `aio app use` command to define your workspace. - - ```bash - aio app use - ``` - - The following menu displays in the terminal: - - ```terminal - You are currently in: - 1. Org: - 2. Project: - 3. Workspace: - - ? Switch to a new Adobe Developer Console configuration: A. Use the global Org / Project / Workspace configuration: - 1. Org: - 2. Project: - 3. Workspace: - - ? The file //.env already exists: Merge - - ✔ Successfully imported configuration for: - 1. Org: - 2. Project: - 3. Workspace: - ``` - -At this point, the `.env` and `.aio` files should be populated. You can remove any leftover property, such as `AIO_ims_contexts_` from the `.env` file. - -Test your configuration by running `npm run deploy` to deploy your application into App Builder. - -#### Add your encryption keys - -The credentials stored in the application are encrypted using an AES-256 algorithm. You must generate a set of custom encryption keys and provide them to the `.env` file to secure authentication data. - -| Key | Description | -|----------------|----------------------------------| -| ENCRYPTION_KEY | 32 character long encryption key | -| ENCRYPTION_IV | Initialization vector | - -#### Add your Adobe Commerce credentials - -The application needs to connect to an Adobe Commerce instance to retrieve the product catalog updates and to ingest Amazon orders. Define the following variables inside the `.env` file: - -| Key | Description | -| --- | --- | -| ADOBE_COMMERCE_BASE_URL | The base URL of your Adobe Commerce instance | -| ADOBE_COMMERCE_CONSUMER_KEY | The consumer key of the integration created in Adobe Commerce | -| ADOBE_COMMERCE_CONSUMER_SECRET | The consumer secret of the integration created in Adobe Commerce | -| ADOBE_COMMERCE_ACCESS_TOKEN | The access token of the integration created in Adobe Commerce | -| ADOBE_COMMERCE_ACCESS_TOKEN_SECRET | The access token secret of the integration created in Adobe Commerce | - -### Configure Required Events in Commerce - -Amazon Sales Channel on App Builder requires using I/O Events to automatically detect and respond to changes in your Commerce product catalog. The `observer.catalog_product_save_after event` is emitted when products are updated, such as when a product's name or price changes. You must configure this event and the fields that the event payload contains as part of setup. This event will be sent from Commerce to your App Builder application. By subscribing to the event published by Commerce, Amazon Sales Channel knows when your Commerce product catalog changes and can automatically make the relevant updates to your Amazon Marketplace product listings. - -Create the `etc/io_events.xml` file in the root directory of your module, if it has not already been created. Register the `observer.catalog_product_save_after` event using the following code. If this event is already registered, ensure that it has all of the required fields. - -```xml - - - - - - - - - - -``` - -See [I/O Events for Adobe Commerce](../../events/module-development.md#io_eventsxml) for more details. Adobe recommends using the `io_events.xml` method to configure events, but you can also configure events by modifying the `app.config` file or by using the CLI. The same event and fields are required, regardless of the method implemented. - -### Subscribe to Adobe Commerce events - -1. Ensure that your Adobe Commerce instance is registered as an event provider as described in [Subscribe and register events](../../events/configure-commerce.md#subscribe-and-register-events). - -1. Register the `observer.catalog_product_save_after` event in your project in [developer console](https://developer.adobe.com/console/). - - * Add a new service of type `Event`. - * Select your event provider. - * Choose the `observer.catalog_product_save_after` event subscription. - * Select the JWT credential. - * Set a name for your event registration. - * Select your Runtime action, which should be similar to `amazon-app/__secured_catalog-product-save-after-listener - -`, then save the event. - -At this point, if you go to the `Debug tracing` area in your new event created inside the [developer console](https://developer.adobe.com/console/), you should be able to see any incoming events from your Adobe Commerce instance. - -## Local Dev environment - -1. Compile the TypeScript files in the `actions-src` directory into `actions`. - - ```bash - npm run compile - ``` - -1. Start your local dev server. - - ```bash - aio app run - ``` - - By default, the app runs on `localhost:9080`. If the port is not available,check the console logs for the updated port. - - The UI is served locally, but actions are deployed and served from Adobe I/O Runtime. To start a local serverless stack and also run your actions locally, use the `aio app run --local` option. - -## Admin UI SDK - -The Amazon Sales Channel on App Builder is securely injected into the Commerce Admin experience using the [Admin UI SDK](../../admin-ui-sdk/index.md). This UI extensibility functionality enables merchant administrators to use a seamless app UI experience in the Commerce Admin. This sample app is just one example of how App Builder integrations can extend Commerce Admin with their own apps' UI. - -[Admin configuration and testing](../../admin-ui-sdk/configuration.md) describes how to test functionality locally. For testing in production, push the Amazon Sales Channel app to production and have an administrator approve the app. - -## Test the app - -Use the following commands to run unit tests: - -```bash -aio app test #runs UI and actions tests -``` - -```bash -aio app test --e2e #runs end-to-end tests -``` - -### Adding additional action dependencies - -You have two options to resolve your action's dependencies: - -* **Packaged action file**: Add your actions dependencies to the root `package.json` and install them using `npm install`. Then set the `function` field in `ext.config.yaml` to point to the **entry file** of your action folder. `webpack` is used to package your code and dependencies into a single minified `js` file. The action will then be deployed as a single file. Use this method if you want to reduce the size of your actions. - -* **Zipped action folder**: In the folder containing the action code, add a `package.json` with the action dependencies. Then set the `function` field in `ext.config.yaml` to point to the **folder** of that action. The required dependencies are installed within that directory. In addition, the process zips the folder before deploying it as a zipped action. Use this method if you want to keep your action's dependencies separated. - -### Debugging in VS Code - -Both UI and actions can be debugged while your local server is running. To start debugging, open the VS Code debugger and select the `WebAndActions` debugging configuration. Other debug configurations are also available for the UI and each separate action. - -## Deploy the app - -Run the following command to compile, build, and deploy all TypeScript actions on Runtime and static files to CDN. - -```bash -npm run deploy -``` - -The `aio app undeploy` command undeploys the app. - -## Typescript support for UI - -Use the `.tsx` extension to designate TypeScript for React components. Also, create a `tsconfig.json` file that defines the following configuration: - -```json -{ - "compilerOptions": { - "jsx": "react" - } -} -``` diff --git a/src/pages/app-development/amazon-sales-channel/prerequisites.md b/src/pages/app-development/amazon-sales-channel/prerequisites.md deleted file mode 100644 index ac9ab4bf6..000000000 --- a/src/pages/app-development/amazon-sales-channel/prerequisites.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Prerequisites -description: Determine what software you need to install the Amazon Sales Channel app and how to configure your Amazon Seller Central account. -keywords: - - App Builder - - Extensibility ---- - -# Prerequisites - -This topic describes how to set up your local development environment so that you can install the Adobe Sales Channel reference app on an Adobe Commerce 2.4.5+ instance. - -To install the reference app, you must: - -* Have an Adobe Developer account with System Administrator or Developer Role permissions. [Getting started with Adobe Developer Console](https://developer.adobe.com/developer-console/docs/guides/getting-started/) describes how to enroll in the Adobe developer program. - -* Be familiar with [Adobe I/O Runtime](https://developer.adobe.com/app-builder/docs/get_started/runtime_getting_started/) and [Adobe IO Events](https://developer.adobe.com/runtime/docs/). - -* Install the [`aio CLI`](https://developer.adobe.com/app-builder/docs/get_started/runtime_getting_started/setup/) - -* Have access to an Adobe Commerce 2.4.5+ on cloud infrastructure or to an on-premises instance. - -* (Recommended) Install [Adobe Commerce Admin UI SDK](../../admin-ui-sdk/index.md), which enables you to attach the App Builder application to the Adobe Commerce Admin. - -* Install [nodeJS 16.13+](https://nodejs.org/en/download) as your JavaScript runtime. - -In addition to these software requirements, you must have access to the Commerce environment from an external network. You must also have the ability to add API integrations. - -## Adobe Commerce configuration and setup - -Before you begin the process of installing the Adobe Sales Channel reference app, you must configure I/O Events for Adobe Commerce and add custom attributes to the Admin. - -### Configure I/O Events for Adobe Commerce - -Follow the instructions in [Configure Adobe Commerce](../../events/configure-commerce.md/) to enable communication with Adobe I/O and create an event provider. Specifically, follow these procedures: - -* [Configure the Adobe I/O connection](../../events/configure-commerce.md#configure-the-adobe-io-connection) - -* [Create an event provider and complete the Commerce configuration](../../events/configure-commerce.md#create-an-event-provider) - -Do not perform the **Subscribe and register events** procedure. The Amazon Sales Channel app [installation](installation.md) instructions describe the process for this app. - -### Create custom attributes - -To subscribe to catalog update events from Adobe Commerce, you must create the following custom attributes in **Stores** > **Attributes** > **Product** > **Add New Attribute**: - -| Default label | Attribute Code | Scope | Notes | -| --- | --- | --- | --- | -| ASIN | `asin` | Global | | -| Amazon Condition | `amazon_condition` | Global | Condition of the listing item. The [Amazon docs](https://developer-docs.amazon.com/sp-api/docs/listings-items-api-v2021-08-01-reference#conditiontype) list the possible values. | - -## Amazon SP API - -Amazon Sales Channel uses [Amazon SP API](https://github.com/amz-tools/amazon-sp-api) to communicate with Amazon Seller Central. - -To properly configure Amazon SP API, you must have: - -* Admin access to [Amazon Seller Central](https://sellercentral.amazon.com/) -* Permissions to add Developer Applications - -You must perform configuration tasks for Amazon Web Services and Amazon Seller Central. - -### Amazon Web Services - -Create an IAM policy per [Amazon SPI Guide](https://developer-docs.amazon.com/sp-api/docs/creating-and-configuring-iam-policies-and-entities). - -### Amazon Seller Central - -The app type of Amazon Sales Channel is **Private Seller**. Specify this integration type when you configure your instance. See [Determine app type](https://developer-docs.amazon.com/sp-api/docs/determine-app-type) for more information. - -1. [Register yourself as a private developer](https://developer-docs.amazon.com/sp-api/docs/registering-as-a-developer#to-register-as-a-private-developer-for-private-seller-applications). - -1. [Registering your Application](https://developer-docs.amazon.com/sp-api/docs/registering-your-application). - -1. [Self authorize](https://developer-docs.amazon.com/sp-api/docs/self-authorization) your application to generate access keys. - -When you create an account from the App Builder application UI, you will need the following set of Amazon credentials: - -| Field | Where to get | -| --- | --- | -| Client ID | In [Developer Central](https://sellercentral.amazon.com/marketplacedeveloper/applications) | -| Client secret | In [Developer Central](https://sellercentral.amazon.com/marketplacedeveloper/applications) | -| Client refresh token | In [Developer Central](https://sellercentral.amazon.com/marketplacedeveloper/applications) > **Authorize** | -| AWS access key | In [AWS](https://aws.amazon.com/) > **IAM** > **User with access to IAM role** | -| AWS secret access key | In [AWS](https://aws.amazon.com/) > **IAM** > **User with access to IAM role** | -| AWS Role ARN | Create [AWS](https://aws.amazon.com/) IAM role | -| Target marketplace | [ASC Marketplace IDs](https://developer-docs.amazon.com/sp-api/docs/marketplace-ids) | -| Unique Seller ID | [Amazon Seller Central](https://sellercentral.amazon.com) > **Account Info** > **Merchant Token** | diff --git a/src/pages/app-development/amazon-sales-channel/release-notes.md b/src/pages/app-development/amazon-sales-channel/release-notes.md deleted file mode 100644 index 8b1d4cdd5..000000000 --- a/src/pages/app-development/amazon-sales-channel/release-notes.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Release notes -description: This page lists new features and known issues for each release of Amazon Sales Channel on App Builder 1.0.0 -keywords: - - App Builder - - Extensibility ---- - -# Release notes - -## Version 1.0.0 - -### Release date - -June 13, 2023 - -### Compatibility - -Adobe Commerce for Cloud and on-premises - -* 2.4.5 and higher - -### Known limitations - -Amazon Sales Channel on App Builder is a reference app that demonstrates how Adobe Developer App Builder can create integrations and extensions without modifying the core Commerce application. This app is not intended or supported for production use. - -The sample app functionality represents only a subset of the original PHP extension's capabilities. For example, it does not include order management or listing and pricing rules. diff --git a/src/pages/app-development/best-practices/credentials.md b/src/pages/app-development/best-practices/credentials.md index a75b93f9f..bf6a4c9ef 100644 --- a/src/pages/app-development/best-practices/credentials.md +++ b/src/pages/app-development/best-practices/credentials.md @@ -8,6 +8,10 @@ keywords: # Credentials management + + +This topic references the Amazon Sales Channel reference app, which is no longer available. However, the methods described in this topic can be applied to any App Builder application that requires credential management. + App Builder is an excellent framework for building integrations that connect Commerce to 3rd-party systems like Amazon or ERPs. These systems often require credentials to support your application to securely communicate and update them. The Amazon Sales Channel app requires credentials and secrets to perform certain actions and interact with the Amazon API. These items must be changed every 180 days to comply with Amazon standards, and they could be updated in runtime. Therefore, creating a static set of credentials is not an option. diff --git a/src/pages/app-development/best-practices/database-storage.md b/src/pages/app-development/best-practices/database-storage.md index ec63fd09b..f527371f2 100644 --- a/src/pages/app-development/best-practices/database-storage.md +++ b/src/pages/app-development/best-practices/database-storage.md @@ -8,6 +8,10 @@ keywords: # Database storage + + +This topic references the Amazon Sales Channel reference app, which is no longer available. However, the methods described in this topic can be applied to any App Builder application that requires storage. + Adobe Developer App Builder is a cloud native framework that has storage capabilities for both long-term and short-term storage. The [Adobe I/O Files](https://github.com/adobe/aio-lib-files) and [Adobe I/O State](https://github.com/adobe/aio-lib-state) libraries provide zero-config file and state caching for App Builder. The Adobe I/O State library is an npm module that provides a JavaScript abstraction on top of distributed/cloud databases with a simple key-value store state persistence API. The Adobe I/O Files library provides a JavaScript abstraction on top of cloud blob storage with a simple file-system like persistence API. Use the state library for storing and accessing small values and the files library for storing larger amounts of data. diff --git a/src/pages/app-development/best-practices/logging-troubleshooting.md b/src/pages/app-development/best-practices/logging-troubleshooting.md index 732520f98..3a08e65f0 100644 --- a/src/pages/app-development/best-practices/logging-troubleshooting.md +++ b/src/pages/app-development/best-practices/logging-troubleshooting.md @@ -8,6 +8,10 @@ keywords: # Logging and troubleshooting + + +This topic references the Amazon Sales Channel reference app, which is no longer available. However, the methods described in this topic can be applied to any App Builder application. + Adobe Developer App Builder offers different options to facilitate logging from code and for viewing and forwarding applications logs as needed. You can opt for the default setting, which involves retrieving logs directly from the IO Runtime, or you can forward them to other destinations like Splunk or Azure Log Analytics. This topic describes implementing the default option and forwarding to Splunk. ## Adobe I/O Runtime (default) diff --git a/src/pages/app-development/learning-path.md b/src/pages/app-development/learning-path.md index 80b3d39df..4b16a91be 100644 --- a/src/pages/app-development/learning-path.md +++ b/src/pages/app-development/learning-path.md @@ -20,7 +20,6 @@ The following resources will help you get to know the extensibility options offe - [Introducing App Builder for Commerce](https://experienceleague.adobe.com/docs/commerce-learn/tutorials/adobe-developer-app-builder/introduction-to-app-builder.html) - A high-level business value proposition and ecosystem. - [Use Cases](https://www.youtube.com/watch?v=spm90jwC94A&t=1s) - a one-hour video on common App Builder use cases. -- [Sample App](./amazon-sales-channel/index.md) - An internally developed sample app with best practices and references to an example GitHub repo. - [Demo](https://experienceleague.adobe.com/docs/commerce-learn/tutorials/adobe-developer-app-builder/app-builder-functional-demonstration.html) - A short video demonstrating a functional integration between Commerce and Amazon Marketplace. ## How can I get set up?