Skip to content

@W-17554979@ Commerce-sdk-react readme updates #2212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vcua-mobify merged 3 commits into from
Jan 17, 2025
Merged

@W-17554979@ Commerce-sdk-react readme updates #2212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
73d4b33
Commerce-sdk-react readme updates
vcua-mobify Jan 17, 2025
6b50cc1
Update changelog
vcua-mobify Jan 17, 2025
1a1b202
More readme changes
vcua-mobify Jan 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/commerce-sdk-react/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
## v3.2.0-dev (Oct 29, 2024)
- Allow cookies for ShopperLogin API [#2190](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2190
- Fix refresh token TTL warning from firing when override is not provided [#2114](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2114)
- Readme updates for private clients [#2212](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2212)

- Update CacheUpdateMatrix for mergeBasket mutation [#2138](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2092)
- Clear auth state if session has been invalidated by a password change [#2092](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2092)
Expand Down
75 changes: 13 additions & 62 deletions packages/commerce-sdk-react/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ In practice, we recommend:
npm install @salesforce/commerce-sdk-react @tanstack/react-query
```

## ⚡️ Quickstart (PWA Kit v2.3.0+)
## ⚡️ Quickstart (PWA Kit v3.0+)

To integrate this library with your PWA Kit application you can use the `CommerceApiProvider` directly assuming that you use the `withReactQuery` higher order component to wrap your `AppConfig` component. Below is a snippet of how this is accomplished.

Expand All @@ -54,6 +54,10 @@ import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
import {withReactQuery} from '@salesforce/pwa-kit-react-sdk/ssr/universal/components/with-react-query'

const AppConfig = ({children}) => {
const headers = {
'correlation-id': correlationId
Copy link
Contributor

@unandyala unandyala Jan 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May be add comment explaining the need for correlation id

Copy link
Contributor Author

@vcua-mobify vcua-mobify Jan 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This bit was just me copying the code that we already have inside app-config in the template-retail-react-app and the generator so that the example more closely aligns with the actual code that developers will see.

}

return (
<CommerceApiProvider
clientId="12345678-1234-1234-1234-123412341234"
Expand All @@ -64,6 +68,11 @@ const AppConfig = ({children}) => {
shortCode="12345678"
locale="en-US"
currency="USD"
headers={headers}
// Uncomment 'enablePWAKitPrivateClient' to use SLAS private client login flows.
// Make sure to also enable useSLASPrivateClient in ssr.js when enabling this setting.
// enablePWAKitPrivateClient={true}
logger={createLogger({packageName: 'commerce-sdk-react'})}
>
{children}
</CommerceApiProvider>
Expand Down Expand Up @@ -125,68 +134,10 @@ export default App

_💡 This section assumes you have read and completed the [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) guide._

To help reduce boilerplate code for managing shopper authentication, by default, this library automatically initializes shopper session and manages the tokens for developers. Currently, the library supports the [Public Client login flow](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html).

Commerce-react-sdk supports both public and private flow of the [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) guide._
You can choose to use either public or private slas to login. By default, public flow is enabled.

#### How private SLAS works
This section assumes you read and understand how [private SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) flow works

To enable private slas flow, you need to pass your secret into the CommercerProvider via clientSecret prop.
**Note** You should only use private slas if you know you can secure your secret since commercer-sdk-react runs isomorphically.

```js
// app/components/_app-config/index.jsx

import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
import {withReactQuery} from '@salesforce/pwa-kit-react-sdk/ssr/universal/components/with-react-query'

const AppConfig = ({children}) => {
return (
<CommerceApiProvider
clientId="12345678-1234-1234-1234-123412341234"
organizationId="f_ecom_aaaa_001"
proxy="localhost:3000/mobify/proxy/api"
redirectURI="localhost:3000/callback"
siteId="RefArch"
shortCode="12345678"
locale="en-US"
currency="USD"
clientSecret="<your-slas-private-secret>"
>
{children}
</CommerceApiProvider>
)
}
```
#### Disable slas private warnings
Copy link
Contributor Author

@vcua-mobify vcua-mobify Jan 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm opting to remove this section around how you can set a client secret directly to the SDK since this can lead to the client secret appearing client-side. Even in the non-PWA scenario, you will want to protect the client secret by adding it server side via a BFF layer.

By default, a warning as below will be displayed on client side to remind developers to always keep their secret safe and secured.
```js
'You are potentially exposing SLAS secret on browser. Make sure to keep it safe and secure!'
```
You can disable this warning by using CommerceProvider prop `silenceWarnings`
To help reduce boilerplate code for managing shopper authentication, by default, this library automatically initializes shopper session and manages the tokens for developers. Commerce-sdk-react supports both the [SLAS Public Client login flow](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [SLAS Private Client login flow](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html). Authorization using a private client is supported in PWA Kit 3.5 and later, and is the recommended authorization workflow.

```js
const AppConfig = ({children}) => {
return (
<CommerceApiProvider
clientId="12345678-1234-1234-1234-123412341234"
organizationId="f_ecom_aaaa_001"
proxy="localhost:3000/mobify/proxy/api"
redirectURI="localhost:3000/callback"
siteId="RefArch"
shortCode="12345678"
locale="en-US"
currency="USD"
clientSecret="<your-slas-private-secret>"
silenceWarnings={true}
>
{children}
</CommerceApiProvider>
)
}
```
#### Using a private SLAS client
To enable a private client, see [Use a SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.html).

### Shopper Session Initialization

Expand Down
Loading