SDK Reference
SDK reference for @chordcommerce/gatsby-theme-performance (Shopify based-sites)

Introduction

The Chord client-side Javascript SDK is installed as a Gatsby theme. It's available as an npm package, @chordcommerce/gatsby-theme-performance, via GitHub Packages.
Despite the name, this package does not provide a visual theme. To quote from the Gatsby documentation:
Gatsby themes are plugins that include a gatsby-config.js file and add pre-configured functionality, data sourcing, and/or UI code to Gatsby sites. You can think of Gatsby themes as separate Gatsby sites that can be put together and allow you to split up a larger Gatsby project!
The gatsby-theme-performance theme includes the Chord SDK, a set of methods you can import and use in your React components to do things like add items to a cart and check out. The theme also pre-configures your Gatsby site with a number of useful commerce features like product feeds and internationalization support.
The Chord SDK is available to use in your React components via React hooks:

useAnalytics()

The useAnalytics hook returns a series of methods that fire a tracking event to Segment, our integrated customer data platform.
Most Segment tracking is done automatically by the SDK. For example, when you use the addToCart method (see useCart), a corresponding track API call to Segment is made. However, some track calls need to be closely tied to the UI, as in the case of tracking clicks on elements, and these calls need to be explicitly made from your React components. Methods for making these calls are available via the useAnalytics hook and listed below.
1
import { useAnalytics } from '@chordcommerce/gatsby-theme-performance'
2
3
const {
4
trackCartViewed,
5
trackCollectionClicked,
6
trackEmailCaptured,
7
trackProductClicked,
8
trackProductListFiltered,
9
trackProductListViewed,
10
trackProductViewed,
11
trackPromotionClicked,
12
trackPromotionViewed,
13
trackStockRequestCreated
14
} = useAnalytics()
Copied!

trackCartViewed()

Results in a Cart Viewed trackevent in Segment.
1
trackCartViewed()
Copied!

trackCollectionClicked()

Results in a Collection Clicked track event in Segment.
1
trackCollectionClicked({ id, description, imageUrl, slug, title })
Copied!

trackEmailCaptured()

Results in a Email Captured track event in Segment.
1
trackEmailCaptured({
2
email: '[email protected]',
3
placement: 'footer'
4
})
Copied!

trackProductClicked()

Results in a Product Clicked track event in Segment.
1
trackProductClicked({ productHandle: 'product-1' })
Copied!

trackProductListFiltered()

Results in a Product List Filtered track event in Segment.
1
trackProductListFiltered({
2
filter: {
3
type: 'color',
4
value: 'red'
5
},
6
list: {
7
category: 'shirt',
8
id: '123'
9
},
10
sort: {
11
type: 'ascending',
12
value: 'price'
13
}
14
})
Copied!

trackProductListViewed()

Results in a Product List Viewed track event in Segment.
1
trackProductListViewed({
2
list: {
3
category: 'shirt',
4
id: '123'
5
}
6
})
Copied!

trackProductViewed()

Results in a Product Viewed track event in Segment.
1
trackProductViewed({ productHandle: 'product-1' })
Copied!

trackPromotionClicked()

Results in a Promotion Clicked track event in Segment.
1
trackPromotionClicked({
2
creative: 'apple',
3
id: '123',
4
name: 'red-shirt-sale',
5
position: 'banner'
6
})
Copied!

trackPromotionViewed()

Results in a Promotion Viewed track event in Segment.
1
trackPromotionClicked({
2
creative: 'apple',
3
id: '123',
4
name: 'red-shirt-sale',
5
position: 'banner'
6
})
Copied!

trackStockRequestCreated()

Results in a Stock Request Created track event in Segment.
1
trackStockRequestCreated({
2
3
productHandle: 'product-1'
4
})
Copied!

useAuth()

The useAuth hook returns a series of methods that enable authentication with a Shopify customer account.
1
import { useAuth } from '@chordcommerce/gatsby-theme-performance'
2
3
const {
4
isLoggedIn,
5
status,
6
getToken,
7
login,
8
logout,
9
recover,
10
register,
11
resetPassword
12
} = useAuth()
Copied!

isLoggedIn

Boolean indicating whether a user is currently logged in.

status

String indicating the status of authentication in Redux. This string can be used to determine if the authentication status has been verified yet, which happens asynchronously after page load.
1
import { useAuth, AuthStatus } from '@chordcommerce/gatsby-theme-performance'
2
3
const { status } = useAuth()
4
5
if (status === AuthStatus.Failed) {
6
// the authentication session has been checked and there is no current valid session
7
}
Copied!

getToken()

Retrieves the current Shopify customer access token.
1
const token = await getToken()
Copied!

login()

Submits the email address and password for a Shopify customer and initiates an authentication session. This method creates a Shopify customer access token.
1
await login({ email: '[email protected]', password: 'testtest' })
Copied!

logout()

Clears the authentication session. This method destroys the current Shopify customer access token.
1
await logout()
Copied!

recover()

Sends a Shopify reset password email to the customer.
1
await recover('[email protected]')
Copied!

register()

Creates a new Shopify customer and initiates an authentication session. This method creates a Shopify customer access token.
1
await register({ email: '[email protected]', password: 'testtest' })
Copied!

resetPassword()

Resets a Shopify customer’s password with an id and token from a Shopify reset password email.
1
await resetPassword({
2
id: 'id',
3
password: 'testtests', // the new password
4
token: '123'
5
})
Copied!

useCart()

The useCart hook returns a series of methods for interacting with the Shopify shopping cart.
1
import { useCart } from '@chordcommerce/gatsby-theme-performance'
2
3
const {
4
cart,
5
addPromoCode,
6
addToCart,
7
applyGiftCard,
8
checkout,
9
loadCart,
10
modifyQuantity,
11
removeFromCart,
12
removeGiftCard,
13
removePromoCode
14
} = useCart()
Copied!

cart

Represents the current shopping cart.
1
const { cart } = useCart()
Copied!

addPromoCode()

Applies a promo code to the current order.
1
const promoCode = '50off'
2
await addPromoCode(promoCode)
Copied!

addToCart()

Adds an item to the current order.
1
const variantId = '123'
2
const quantity = 1
3
await addToCart(variantId, quantity)
Copied!

applyGiftCard()

Applies a gift card to the current order.
1
const giftCardCode = 'xxxyyyzzz'
2
await applyGiftCard(giftCardCode)
Copied!

checkout()

Redirects the browser to Shopify checkout.
1
await checkout()
Copied!

loadCart()

Reloads the current shopping cart. This is automatically called on every page load and with every other useCart method.
1
await loadCart()
Copied!

modifyQuantity()

Updates the quantity of a line item in the current order.
1
const lineItemId = '123'
2
const quantity = 2
3
await modifyQuantity(lineItemId, quantity)
Copied!

modifyLineItem()

Updates a line item in the current order.
1
const lineItemId = '123'
2
3
// update line item quantity
4
await modifyQuantity(lineItemId, {
5
quantity: 2,
6
})
7
8
// update line item customAttributes
9
await modifyQuantity(lineItemId, {
10
customAttributes: [
11
{
12
key: 'Est. Shipping Date',
13
value: 'March 24, 2022',
14
}
15
],
16
})
Copied!

removeFromCart()

Removes a line item from the current order.
1
const lineItemId = '123'
2
await removeFromCart(lineItemId)
Copied!

removeGiftCard()

Removes a gift card from the current order.
1
const giftCardCode = 'xxxyyyzzz'
2
await removeGiftCard(giftCardCode)
Copied!

removePromoCode()

Removes a promo code from the current order.
1
const promoCode = '50off'
2
await removePromoCode(promoCode)
Copied!

useUser()

The useUser hook returns a series of methods for managing a Shopify customer account. The customer must have an active authentication session (see useAuth) for these methods to work.
1
import { useUser } from '@chordcommerce/gatsby-theme-performance'
2
3
const {
4
user,
5
status,
6
createUserAddress,
7
loadUser,
8
modifyUserAddress,
9
modifyUserDefaultAddress,
10
removeUserAddress
11
} = useUser()
Copied!

user

Represents the current user.
1
const { user } = useUser()
Copied!

status

String indicating the status of the user in Redux. This string can be used to determine if the user has been loaded yet, which happens asynchronously after page load.
1
import { useUser, UserStatus } from '@chordcommerce/gatsby-theme-performance'
2
3
const { status } = useUser()
4
5
if (status === UserStatus.Failed) {
6
// the user could not be loaded, probably because there is no valid authentication session
7
}
Copied!

createUserAddress()

Adds a new address to the Shopify customer's address book.
1
const address = {
2
address1: '',
3
address2: '',
4
city: '',
5
company: '',
6
country: '',
7
firstName: '',
8
lastName: '',
9
phone: '',
10
province: '',
11
zip: ''
12
}
13
const isDefaultAddress = false
14
await createUserAddress(address, isDefaultAddress)
Copied!

loadUser()

Reloads the current user. This is automatically called on every page load and with every other useUser method.
1
await loadUser()
Copied!

modifyUserAddress()

Updates an address in the Shopify customer's address book.
1
const addressId = '123'
2
const address = {
3
address1: '',
4
address2: '',
5
city: '',
6
company: '',
7
country: '',
8
firstName: '',
9
lastName: '',
10
phone: '',
11
province: '',
12
zip: ''
13
}
14
const isDefaultAddress = false
15
await modifyUserAddress(addressId, address, isDefaultAddress)
Copied!

modifyUserDefaultAddress()

Updates which address is marked as the default address in the Shopify customer's address book.
1
const addressId = '123'
2
await modifyUserDefaultAddress(addressId)
Copied!

removeUserAddress()

Removes an address from the Shopify customer's address book.
1
const addressId = '123'
2
await removeUserAddress(addressId)
Copied!