@salesforce/cc-datacloud-typescript

cc-datacloud-typescript

cc-datacloud-typescript is a Typescript SDK that aids the developer on sending shopper interactions from their Typescript app to Salesforce Data Cloud.

This SDK includes the methods and types needed to successfully integrate the app with autoconfigured commerce mappings in Data Cloud.

How to use this SDK

Data Cloud Setup

• Have a working Data Cloud instance with a website connector configured.

Steps

1. Download the Data Kit which includes the configuration for utilizing this SDK with your Data Cloud Org.

Dev Environment datakit Prod Environment datakit

2. Get your Tenant ID and App Source ID

You will be needing your tenant id and app source id to configure the Typescript SDK.

• Tenant ID is located at Data Cloud setup
• Go to Data Cloud Setup and scroll down in the landing page. You will see tenantSpecificEndpoint which it will include the tenant ID as the first part in the url: <TENANT_ID>.pc-rnd.c360a.salesforce.com
• App Source ID is located at your configured website connector
• Go to your connector and scroll down in the main page. Under Integration Guide you will see Content Delivery Network Script which will include your app source id: https://cdn.pc-rnd.c360a.salesforce.com/beacon/c360a/<YOUR_APP_SOURCE_ID>/scripts/c360a.min.js

Build the Repository

• Clone this repo using git clone

• Change to the root directory of your repo and run yarn install or npm install

• Then run yarn build:lib or npm run build:lib

• Run yarn link or npm link. This will allow this SDK can be used in your local system by other javascript/typescript projects.

• Go to your app source and install (link) this SDK. Based on your package manager, run one of these commands:

  • If yarn, then use yarn add cc-datacloud-typescript
  • If npm, then use npm link cc-datacloud-typescript

• Enjoy using the SDK!

Sample Usage

Here is an example of sending an interaction Type: AddToCart

With Typescript Client

import {initDataCloudSdk} from 'cc-datacloud-typescript'
import {DataCloudApi} from 'cc-datacloud-typescript/lib'
import {AddToCartBuilder, Cart, CartItem, Identity, PartyIdentification} from 'cc-datacloud-typescript/models'

const currentDateTime = new Date().toISOString() 

const tenantId = 'xxxxxx'; // From above "Data Cloud Setup" step
const appID = 'xxxxx-xxxx-xxxx-xxxx-xxxxx'; // From above "Data Cloud Setup" step

const cartEventId =  crypto.randomUUID();

const sdk: DataCloudApi = initDataCloudSdk(tenantId, appID); 

// These are just sample values, they can be different for your application
const cart: Cart = {
    currency: 'USD',
    eventType: 'cart',
    eventId: 'xxxxxxxx-35b0-421d-8a34-32be4d5exxxx',
    dateTime: '2024-07-03T18:17:06.062Z',
    sessionId: 'aBcd1L2j3n6cSZH+jod2ZMUlgnU6p000',
    deviceId: 'abcd299068c7b941341e048e',
    sourceUrl: 'http://127.0.0.1:3000/',
    sourceUrlReferrer: 'http://127.0.0.1:3000/',
    sourceChannel: 'Web',
    category: 'Engagement',
    siteId: 'example-site',
    id: 'example-sdk-cart-id',
    interactionName: "cart-add",
    eventStatus: "success",
    webStoreId: "9bd24cb7-0000-0000-0000-cd4225bd8ebd"
}

const cartItem: CartItem = {
    eventId: 'xxxxxxxx-35b0-421d-8a34-32be4d5exxxx',
    dateTime: '2024-07-03T18:17:06.062Z',
    eventType: 'cartItem',
    category: 'Engagement',
    deviceId: 'abcd299068c7b941341e048e',
    sessionId: 'aBcd1L2j3n6cSZH+jod2ZMUlgnU6p000',
    siteId: 'example-site',
    personalizationContentId: 'personalizationContentId',
    catalogObjectId: '00ae676xxx',
    catalogObjectType: 'product',
    cartEventId: 'c9c605e8-0000-0000-0000-9382a8ff568e',
    lineItemId: 'abcd4ffc03b09dab4dd34063',
    price: 45,
    quantity: 3,
    imageUrl: 'localhost:3000/SuperContraption.jpg',
    name: 'product-name'
}

const identity: Identity = {
    isAnonymous: "1",
    firstName: "TestFirstName",
    lastName: "TestLastName",
    country: "us",
    sourceLocale: "en_US",
    sourceUrlReferrer: "https://localhost/on/demandware",
    eventId: 'xxxxxxxx-35b0-421d-8a34-32be4d5exxxx',
    dateTime: "2024-07-03T18:17:06.062Z",
    eventType: "identity",
    category: "Profile",
    deviceId: 'abcd299068c7b941341e048e',
    sessionId: 'aBcd1L2j3n6cSZH+jod2ZMUlgnU6p000',
    siteId: 'example-site',
}
// Construct the Interaction to be sent (Typescript only)
const interaction = new AddToCartBuilder()
    .withCart(cart)
    .withCartItem(cartItem)
    .withIdentity(identity)
    .build()
// The Interaction Will be sent to DataCloud Api
sdk.webEventsAppSourceIdPost(interaction)

Javascript Node JS Client

import { initDataCloudSdk } from 'cc-datacloud-typescript';

const currentDateTime = new Date().toISOString();

const cartEventId = crypto.randomUUID();

const tenantId = 'xxxxxx'; // From above "Data Cloud Setup" step
const appID = 'xxxxx-xxxx-xxxx-xxxx-xxxxx'; // From above "Data Cloud Setup" step

const sdk = initDataCloudSdk(tenantId, appID); 

// These are just sample values, they can be different for your application
const cart: Cart = {
    currency: 'USD',
    eventType: 'cart',
    eventId: 'xxxxxxxx-35b0-421d-8a34-32be4d5exxxx',
    dateTime: '2024-07-03T18:17:06.062Z',
    sessionId: 'aBcd1L2j3n6cSZH+jod2ZMUlgnU6p000',
    deviceId: 'abcd299068c7b941341e048e',
    sourceUrl: 'http://127.0.0.1:3000/',
    sourceUrlReferrer: 'http://127.0.0.1:3000/',
    sourceChannel: 'Web',
    category: 'Engagement',
    siteId: 'example-site',
    id: 'example-sdk-cart-id',
    interactionName: "cart-add",
    eventStatus: "success",
    webStoreId: "9bd24cb7-0000-0000-0000-cd4225bd8ebd"
}

const cartItem: CartItem = {
    eventId: 'xxxxxxxx-35b0-421d-8a34-32be4d5exxxx',
    dateTime: '2024-07-03T18:17:06.062Z',
    eventType: 'cartItem',
    category: 'Engagement',
    deviceId: 'abcd299068c7b941341e048e',
    sessionId: 'aBcd1L2j3n6cSZH+jod2ZMUlgnU6p000',
    siteId: 'example-site',
    personalizationContentId: 'personalizationContentId',
    catalogObjectId: '00ae676xxx',
    catalogObjectType: 'product',
    cartEventId: 'c9c605e8-0000-0000-0000-9382a8ff568e',
    lineItemId: 'abcd4ffc03b09dab4dd34063',
    price: 45,
    quantity: 3,
    imageUrl: 'localhost:3000/SuperContraption.jpg',
    name: 'product-name'
}

const identity: Identity = {
    isAnonymous: "1",
    firstName: "TestFirstName",
    lastName: "TestLastName",
    country: "us",
    sourceLocale: "en_US",
    sourceUrlReferrer: "https://localhost/on/demandware",
    eventId: 'xxxxxxxx-35b0-421d-8a34-32be4d5exxxx',
    dateTime: "2024-07-03T18:17:06.062Z",
    eventType: "identity",
    category: "Profile",
    deviceId: 'abcd299068c7b941341e048e',
    sessionId: 'aBcd1L2j3n6cSZH+jod2ZMUlgnU6p000',
    siteId: 'example-site',
};

// Construct the Interaction to be sent in Javascript
const interaction = {
    events: [identity, cart, cartItem]
};

await sdk.webEventsAppSourceIdPost(interaction)

Available Shopper Interactions

Shopper Interactions