Skip to content

Commit c104ce3

Browse files
keharperkeharper
authored
Merge pull request AdobeDocs#34 from AdobeDocs/kh_ASC-install
Add ASC installation instructions
2 parents a1c2f57 + 8a830f5 commit c104ce3

File tree

3 files changed

+340
-6
lines changed

3 files changed

+340
-6
lines changed

‎src/data/navigation/sections/amazon-sales-channel.js

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,17 @@ module.exports = [
44
path: "/amazon-sales-channel/index.md",
55
},
66
{
7-
title: "Installation",
8-
path: "/amazon-sales-channel/installation.md",
7+
title: "Prerequisites",
8+
path: "/amazon-sales-channel/prerequisites.md",
99
},
1010
{
11-
title: "Best Practices",
12-
path: "/amazon-sales-channel/best-practices/index.md",
11+
title: "Installation",
12+
path: "/amazon-sales-channel/installation.md",
1313
},
14+
// {
15+
// title: "Best Practices",
16+
// path: "/amazon-sales-channel/best-practices/index.md",
17+
// },
1418
{
1519
title: "Release Notes",
1620
path: "/amazon-sales-channel/release-notes.md"

‎src/pages/amazon-sales-channel/installation.md

Lines changed: 219 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,223 @@
11
---
2-
title: Installation
2+
title: Install the Amazon Sales Channel app
33
description:
44
---
55

6-
# Installation
6+
# Install the Amazon Sales Channel app
7+
8+
<InlineAlert variant="info" slots="text" />
9+
10+
Review the [Prerequisites](prerequisites.md) before you attempt to install the Amazon Sales Channel app.
11+
12+
## Clone application source code
13+
14+
Clone the `amazon-sales-channel-app-builder` repo to your working directory:
15+
16+
```bash
17+
git clone git@github.com:adobe/amazon-sales-channel-app-builder.git <custom-directory>
18+
```
19+
20+
## Setup project dependencies
21+
22+
Change directories to the cloned repo and run the following commands:
23+
24+
1. Download dependencies and prepare the project.
25+
26+
```bash
27+
npm install
28+
```
29+
30+
1. Build the project.
31+
32+
```bash
33+
npm run build
34+
```
35+
36+
The command cleans, compiles, and runs the `aio app build` command.
37+
38+
## Configure your application
39+
40+
### Add services
41+
42+
In your App Builder project:
43+
44+
1. In your workspace, click the **Add service** pop-up menu and select **API**.
45+
46+
1. On the **Add an API** page, filter on **Adobe Services** and select **I/O Management API**. Then click **Next**.
47+
48+
1. On the **Configure API** page, select the **Service Account (JWT)** option and click **Save configured API**.
49+
50+
**Note**: OAuth Server to Server authentication is not currently supported.
51+
52+
1. Select **Generate key pair**.
53+
54+
1. Click **Save configured API**.
55+
56+
1. Repeat this process and create an `Adobe I/O Events for Adobe Commerce` service.
57+
58+
### Set up your environment
59+
60+
1. From the root of the cloned repo, make a copy of the `.env.dist` file.
61+
62+
```bash
63+
cp .env.dist .env
64+
```
65+
66+
1. Run the `aio app use` command to define your workspace.
67+
68+
```bash
69+
aio app use
70+
```
71+
72+
The following menu displays in the terminal:
73+
74+
```terminal
75+
You are currently in:
76+
1. Org: <no org selected>
77+
2. Project: <no project selected>
78+
3. Workspace: <no workspace selected>
79+
80+
? Switch to a new Adobe Developer Console configuration: A. Use the global Org / Project / Workspace configuration:
81+
1. Org: <your org>
82+
2. Project: <your project>
83+
3. Workspace: <your workspace>
84+
85+
? The file /<project_path>/.env already exists: Merge
86+
87+
✔ Successfully imported configuration for:
88+
1. Org: <your org>
89+
2. Project: <your project>
90+
3. Workspace: <your workspace>
91+
```
92+
93+
At this point, the `.env` and `.aio` files should be populated. You can remove any leftover property, such as `AIO_ims_contexts_<App_Builder_Reference>` from the `.env` file.
94+
95+
Test your configuration by running `npm run deploy` to deploy your application into App Builder.
96+
97+
#### Add your encryption keys
98+
99+
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.
100+
101+
| Key | Description |
102+
|----------------|----------------------------------|
103+
| ENCRYPTION_KEY | 32 character long encryption key |
104+
| ENCRYPTION_IV | Initialization vector |
105+
106+
#### Add your Adobe Commerce credentials
107+
108+
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:
109+
110+
| Key | Description |
111+
| --- | --- |
112+
| ADOBE_COMMERCE_BASE_URL | The base URL of your Adobe Commerce instance |
113+
| ADOBE_COMMERCE_CONSUMER_KEY | The consumer key of the integration created in Adobe Commerce |
114+
| ADOBE_COMMERCE_CONSUMER_SECRET | The consumer secret of the integration created in Adobe Commerce |
115+
| ADOBE_COMMERCE_ACCESS_TOKEN | The access token of the integration created in Adobe Commerce |
116+
| ADOBE_COMMERCE_ACCESS_TOKEN_SECRET | The access token secret of the integration created in Adobe Commerce |
117+
118+
### Configure Required Events in Commerce
119+
120+
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.
121+
122+
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.
123+
124+
```xml
125+
<event name="catalog_product_save_after">
126+
<fields>
127+
<field name="sku" />
128+
<field name="price" />
129+
<field name="stock_data.qty" />
130+
<field name="asin" />
131+
<field name="amazon_condition" />
132+
<field name="name" />
133+
</fields>
134+
```
135+
136+
See [I/O Events for Adobe Commerce](https://developer.adobe.com/commerce/events/get-started/module-development/#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.
137+
138+
### Subscribe to Adobe Commerce events
139+
140+
1. Ensure that your Adobe Commerce instance is registered as an event provider as described in [Subscribe and register events
141+
](https://developer.adobe.com/commerce/events/get-started/configure-commerce/#subscribe-and-register-events).
142+
143+
1. Register the `observer.catalog_product_save_after` event in your project in [developer console](https://developer.adobe.com/console/).
144+
145+
* Add a new service of type `Event`.
146+
* Select your event provider.
147+
* Choose the `observer.catalog_product_save_after` event subscription.
148+
* Select the JWT credential.
149+
* Set a name for your event registration.
150+
* Select your Runtime action, which should be similar to `amazon-app/__secured_catalog-product-save-after-listener - <your project>-<your workspace>`, then save the event.
151+
152+
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.
153+
154+
## Local Dev environment
155+
156+
1. Compile the TypeScript files in the `actions-src` directory into `actions`.
157+
158+
```bash
159+
npm run compile
160+
```
161+
162+
1. Start your local dev server.
163+
164+
```bash
165+
aio app run
166+
```
167+
168+
By default, the app runs on `localhost:9080`. If the port is not available,check the console logs for the updated port.
169+
170+
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.
171+
172+
## Admin UI SDK
173+
174+
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.
175+
176+
[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.
177+
178+
## Test the app
179+
180+
Use the following commands to run unit tests:
181+
182+
```bash
183+
aio app test #runs UI and actions tests
184+
```
185+
186+
```bash
187+
aio app test --e2e #runs end-to-end tests
188+
```
189+
190+
#### Adding additional action dependencies
191+
192+
You have two options to resolve your action's dependencies:
193+
194+
* **Packaged action file**: Add your actions dependencies to the root `package.json` and install them using `npm install`. Then set the `function`
195+
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.
196+
197+
* **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.
198+
199+
### Debugging in VS Code
200+
201+
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.
202+
203+
## Deploy the app
204+
205+
Run the following command to compile, build, and deploy all TypeScript actions on Runtime and static files to CDN.
206+
207+
```bash
208+
npm run deploy
209+
```
210+
211+
The `aio app undeploy` command undeploys the app.
212+
213+
## Typescript support for UI
214+
215+
Use the `.tsx` extension to designate TypeScript for React components. Also, create a `tsconfig.json` file that defines the following configuration:
216+
217+
```json
218+
{
219+
"compilerOptions": {
220+
"jsx": "react"
221+
}
222+
}
223+
```

‎src/pages/amazon-sales-channel/prerequisites.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: Prerequisites
3+
description: Determine what software you need to install the Amazon Sales Channel app and how to configure your Amazon Seller Central account.
4+
---
5+
6+
# Prerequisites
7+
8+
This topic describes how to set up your local development environment so that you can install the Adobe Sales Channel reference app.
9+
10+
You must install [nodeJS 16.13+](https://nodejs.org/en/download) as your JavaScript runtime.
11+
12+
## Adobe Commerce
13+
14+
* (Required) Adobe Commerce 2.4.5+
15+
* (Optional) [Adobe Commerce Admin UI SDK](https://developer.adobe.com/commerce/extensibility/admin-ui-sdk/) enables you to attach the App Builder application to the Adobe Commerce Admin.
16+
17+
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.
18+
19+
### Create custom attributes
20+
21+
To subscribe to catalog update events from Adobe Commerce, you must create the following custom attributes in **Stores** > **Attributes** > **Product** > **Add New Attribute**:
22+
23+
| Default label | Attribute Code | Scope | Notes |
24+
| --- | --- | --- | --- |
25+
| ASIN | `asin` | Global | |
26+
| 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. |
27+
28+
### Subscribe to catalog update events
29+
30+
Use the following steps to configure Commerce and subscribe to catalog update events. The [_Getting started with Adobe I/O Events for Adobe Commerce_](https://developer.adobe.com/commerce/events/get-started/configure-commerce/) guide provides additional context.
31+
32+
1. Register your Commerce instance as an event provider. See [Configure Adobe Commerce](https://developer.adobe.com/commerce/events/get-started/configure-commerce/) for details.
33+
34+
1. After you have configured your instance and the event provider is created, use the following command to subscribe to the `observer.catalog_product_save_after` event:
35+
36+
```bash
37+
bin/magento events:subscribe observer.catalog_product_save_after --fields=sku --fields=price --fields=stock_data.qty --fields=asin --fields=amazon_condition --fields=name
38+
```
39+
40+
## Adobe Developer Console
41+
42+
The [Adobe Developer Console](https://developer.adobe.com/developer-console/docs/guides/getting-started/) allows you to create projects and begin your development journey. Create a project and make sure that you have access to the following:
43+
44+
* [Adobe IO Runtime](https://developer.adobe.com/runtime/docs/)
45+
* [Adobe IO Events](https://developer.adobe.com/runtime/docs/)
46+
47+
### Adobe I/O CLI
48+
49+
The [Adobe I/O CLI](https://developer.adobe.com/runtime/docs/guides/tools/cli_install) allows you to manage your projects and workspaces. Install this essential tool by following these steps:
50+
51+
1. Run `npm install -g @adobe/aio-cli` to install Adobe I/O Extensible CLI.
52+
53+
1. Run `aio login` to authenticate to the developer console.
54+
55+
1. Run `aio console org select` to select your organization.
56+
57+
1. Run `aio console project select` to select your project.
58+
59+
1. Run `aio console workspace select` and select "Stage" as your workspace.
60+
61+
For more information, refer to [Adobe I/O CLI documentation](https://github.com/adobe/aio-cli/blob/master/README.md).
62+
63+
### Adobe Developer App Builder
64+
65+
[Adobe Developer App Builder](https://developer.adobe.com/app-builder/docs/overview/) is a complete framework that enables enterprise developers to build and deploy custom web applications that extend Adobe Commerce and other Experience Cloud solutions and run on Adobe infrastructure.
66+
67+
The following package needs to be installed locally to properly register events:
68+
69+
* [aio-cli-plugin-extension](https://github.com/adobe/aio-cli-plugin-extension)
70+
71+
The following packages need to be installed locally to properly run your `aio` with `--local` flag enabled:
72+
73+
* [Java 11 or higher](https://www.oracle.com/es/java/technologies/javase/jdk11-archive-downloads.html)
74+
* [Maven](https://maven.apache.org/)
75+
* [Docker](https://docs.docker.com/desktop/)
76+
77+
## Amazon SP API
78+
79+
Amazon Sales Channel uses [Amazon SP API](https://github.com/amz-tools/amazon-sp-api) to communicate with Amazon Seller Central.
80+
81+
To properly configure Amazon SP API, you must have:
82+
83+
* Admin access to [Amazon Seller Central](https://sellercentral.amazon.com/)
84+
* Permissions to add Developer Applications
85+
86+
You must perform configuration tasks for Amazon Web Services and Amazon Seller Central.
87+
88+
### Amazon Web Services
89+
90+
Create an IAM policy per [Amazon SPI Guide](https://developer-docs.amazon.com/sp-api/docs/creating-and-configuring-iam-policies-and-entities).
91+
92+
### Amazon Seller Central
93+
94+
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.
95+
96+
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).
97+
98+
1. [Registering your Application](https://developer-docs.amazon.com/sp-api/docs/registering-your-application).
99+
100+
1. [Self authorize](https://developer-docs.amazon.com/sp-api/docs/self-authorization) your application to generate access keys.
101+
102+
When you create an account from the App Builder application UI, you will need the following set of Amazon credentials:
103+
104+
| Field | Where to get |
105+
| --- | --- |
106+
| Client ID | In [Developer Central](https://sellercentral.amazon.com/marketplacedeveloper/applications) |
107+
| Client secret | In [Developer Central](https://sellercentral.amazon.com/marketplacedeveloper/applications) |
108+
| Client refresh token | In [Developer Central](https://sellercentral.amazon.com/marketplacedeveloper/applications) > **Authorize** |
109+
| AWS access key | In [AWS](https://aws.amazon.com/) > **IAM** > **User with access to IAM role** |
110+
| AWS secret access key | In [AWS](https://aws.amazon.com/) > **IAM** > **User with access to IAM role** |
111+
| AWS Role ARN | Create [AWS](https://aws.amazon.com/) IAM role |
112+
| Target marketplace | [ASC Marketplace IDs](https://developer-docs.amazon.com/sp-api/docs/marketplace-ids) |
113+
| Unique Seller ID | [Amazon Seller Central](https://sellercentral.amazon.com) > **Account Info** > **Merchant Token** |

0 commit comments

Comments
 (0)