Skip to content

Commit

Permalink
Add new troubleshooting section and review docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@detonivictor
detonivictor authored Jan 14, 2021
1 parent 581b7c9 commit 2c0174e
Show file tree
Hide file tree
Showing 4 changed files with 216 additions and 26 deletions.
15 changes: 12 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,16 +121,25 @@ In most cases, it should be as simple as running the following in your project:
npm install @croct/plug
```

Then, call [`croct.plug`](docs/plug.md#plug) passing the App ID to initialize the SDK:

```js
import croct from '@croct/plug';

croct.plug({appId: '<APP_ID>'});
```

### Script Tag

To install the SDK as a script tag, add the following line to the `<head>` tag of your site on any pages you plan
to use the SDK to personalize or track events. Next, replace the `<APP_ID>` placeholder with the respective
application's public ID.
To install the SDK as a script tag, add the following line to the `<head>` tag of your site on any pages you plan to use the SDK to personalize or track events:

```html
<script src="https://cdn.croct.io/js/v1/lib/plug.js?appId=<APP_ID>"></script>
<script>croct.plug();</script>
```

You should replace the `<APP_ID>` placeholder with the respective App ID. For more information about the available options, see [`croct.plug`](docs/plug.md#plug).

## Documentation

The following references provide guidance to help you get started, integrate, and troubleshoot problems:
Expand Down
146 changes: 145 additions & 1 deletion docs/events.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ summary of all events available to help you decide which events can benefit your
- [E-commerce Events](#e-commerce-events)
* [productViewed](#productviewed)
* [cartViewed](#cartviewed)
* [cartModified](#cartmodified)
* [checkoutStarted](#checkoutstarted)
* [orderPlaced](#orderplaced)
- [Analytics Events](#analytics-events)
Expand All @@ -51,7 +52,8 @@ There are several event types that you can record within the customer journey:
| [`pageOpened`](#pageopened) | Web | Yes | Records a page open.
| [`pageLoaded`](#pageloaded) | Web | Yes | Records a page load.
| [`productViewed`](#productviewed) | E-commerce | No | Records a product view.
| [`cartViewed`](#cartviewed) | E-commerce | No | Records a cart view.
| [`cartViewed`](#cartviewed) | E-commerce | No | Records a shopping cart view.
| [`cartModified`](#cartmodified) | E-commerce | No | Records a shopping cart change.
| [`checkoutStarted`](#checkoutstarted) | E-commerce | No | Records a checkout start.
| [`orderPlaced`](#orderplaced) | E-commerce | No | Records a placed order.
| [`goalCompleted`](#goalcompleted) | Analytics | No | Records a goal completion.
Expand Down Expand Up @@ -429,6 +431,148 @@ croct.track('cartViewed', {
```
</details>

### cartModified

This event records the user modified the shopping cart.

You should track this event when a user modifies the shopping cart page, either by adding, removing, or updating items.

#### Properties

This event supports the following properties:

| Property | Type | Required | Constraints | Description
|---------------------------------------|----------|----------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| `cart` | `object` | Yes | | The cart information.
| `cart.currency` | `string` | Yes | Between 1 and 10 characters long | The currency in which the monetary values are expressed in the shopping cart. We recommend using the 3-letter currency codes defined by the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard. For currencies having no official recognition in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217), consider using ISO-like codes adopted locally or commercially, such as `XBT` for BitCoin.
| `cart.items` | `array` | Yes | | The list of items.
| `cart.items[*].product` | `object` | Yes | | The product details.
| `cart.items[*].product.productId` | `string` | Yes | Between 1 and 50 characters long | The ID that uniquely identifies the product on your store.
| `cart.items[*].product.sku` | `string` | No | Between 1 and 50 characters long | The code that uniquely identifies the product variant on your store.
| `cart.items[*].product.name` | `string` | Yes | Between 1 and 200 characters long | The name of the product.
| `cart.items[*].product.category` | `string` | No | Between 1 and 100 characters long | The category of the product.
| `cart.items[*].product.brand` | `string` | No | Between 1 and 100 characters long | The brand associated with the product.
| `cart.items[*].product.variant` | `string` | No | Between 1 and 50 characters long | The variant of the product, such as size, color and style.
| `cart.items[*].product.displayPrice` | `number` | Yes | Non-negative | The price of the product displayed in the store.
| `cart.items[*].product.originalPrice` | `number` | No | Non-negative | The original price of the product.
| `cart.items[*].product.url` | `string` | No | Well-formed URL | The URL of the product page.
| `cart.items[*].product.imageUrl` | `string` | No | Well-formed URL | The URL of the main product image.
| `cart.items[*].index` | `number` | Yes | Non-negative | The index, starting from zero, representing the cart in which the item was added to the shopping cart.
| `cart.items[*].quantity` | `number` | Yes | Positive | The number of units of the item.
| `cart.items[*].total` | `number` | Yes | Non-negative | The total for the item. It includes discounts and any other adjustment.
| `cart.items[*].discount` | `number` | No | Non-negative | The amount of the discount applied to the item.
| `cart.items[*].coupon` | `number` | No | Between 1 and 50 characters long | The coupon applied to the item.
| `cart.subtotal` | `number` | No | Non-negative | The total of all items and quantities in the shopping cart including applied item promotions. Applied cart discounts, estimated shipping, and applied shipping discounts should be excluded from the subtotal amount.
| `cart.shippingPrice` | `number` | No | Non-negative | The total shipping price for the items in the shopping cart, including any handling charges.
| `cart.taxes` | `object` | No | Non-empty string keys and values | The taxes associated with the transaction.
| `cart.costs` | `object` | No | Non-empty string keys and values | The costs associated with the transaction, such as manufacturing costs, shipping expenses not borne by the customer, or any other costs.
| `cart.discount` | `number` | No | Non-negative | The amount of the discount applied to the shopping cart.
| `cart.total` | `number` | Yes | Non-negative | The total revenue or grand total associated with the transaction. It includes shipping, tax, and any other adjustment.
| `cart.coupon` | `string` | No | Between 1 and 50 characters long | The coupon applied to the shopping cart.
| `cart.lastUpdateTime` | `number` | No | Non-negative | The time when the shopping cart was last updated, in milliseconds since epoch.

**Note:**

- The `sku` and `productId` do not have to be different. Usually, the `productId` is the internal identifier,
like `12345`, and the SKU is a public-facing identifier like `SM-124-GREEN`.
- The `displayPrice` is the price the user pays, while the `originalPrice` is usually the regular retail price.
- When you don't specify a value for the `lastUpdateTime` property, the SDK considers the time at which you tracked the event as the last update time.

#### Code Sample

Here are some examples of how to track this event:

<details>
<summary>Minimal Example</summary>

```js
croct.track('cartModified', {
cart: {
currency: 'USD',
total: 776.49,
items: [
{
index: 0,
total: 699.00,
quantity: 1,
product: {
productId: '12345',
name: 'Smartphone 9',
displayPrice: 699.00
}
}
]
}
});
```
</details>

<details>
<summary>Complete Example</summary>

```js
croct.track('cartModified', {
cart: {
currency: 'USD',
items: [
{
index: 0,
quantity: 1,
total: 699.00,
discount: 100.00,
coupon: 'PROMO',
product: {
productId: '12345',
sku: 'SM-124-GREEN',
name: 'Smartphone 9',
category: 'Smartphone',
brand: 'Acme',
variant: '64GB Green',
displayPrice: 699.00,
originalPrice: 799.00,
url: 'https://www.acme.com/product/smartphone9',
imageUrl: 'https://www.acme.com/images/smartphone9-64gb-green.png'
}
},
{
index: 1,
quantity: 1,
total: 39.00,
discount: 10.00,
coupon: 'PROMO',
product: {
productId: '98765',
sku: '03132db8-2c37-4aef-9827-60d0206683d9',
name: 'Silicone Case',
category: 'Cases',
brand: 'Acme',
variant: 'Black',
displayPrice: 39.00,
originalPrice: 49.00,
url: 'https://www.acme.com/product/silicone-case',
imageUrl: 'https://www.acme.com/images/silicone-case-black'
}
}
],
taxes: {
state: 53.51,
local: 23.98
},
costs: {
manufacturing: 275.81,
cos: 85.37
},
subtotal: 848.00,
shippingPrice: 59.99,
discount: 169.99,
total: 815.49,
coupon: 'FREE-SHIPPING',
lastUpdateTime: 123456789
}
});
```
</details>

### checkoutStarted

This event records the checkout process started.
Expand Down
35 changes: 35 additions & 0 deletions docs/troubleshooting.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Sometimes things go wrong. Here is a list of resolutions to some of the problems

- [I'm not able to connect my application to the playground](#im-not-able-to-connect-my-application-to-the-playground)
- [Some user attributes remain null even after applying a patch](#some-user-attributes-remain-null-after-applying-a-patch)
- [I installed a plugin, but it didn’t work](#i-installed-a-plugin-but-it-didnt-work)

## I'm not able to connect my application to the playground

Expand Down Expand Up @@ -46,4 +47,38 @@ You can temporarily collect information to let the session unification process a
identified profile when the user signs up. If the user does not signs up, the personalization engine will anonymize
the profile after the session has expired.

## I installed a plugin, but it didn’t work

Forgetting to import the plugin into the same file where we initialized the SDK is the most common cause for a plugin not work. The import is essential for the SDK to discover and load all the plugins you want to use. You also need to enable the plugin explicitly.

The following example shows how to enable the Google Analytics Plugin using the default settings:

```js
import croct from '@croct/plug';

// Install the plugin
import '@croct/plug-google-analytics';
croct.plug({
plugins: {
// Enable the plugin
googleAnalytics: true,
}
});
```

If the problem persists, check if the plugin has been found and loaded. To do this, follow the steps below:

1. Enable the debug mode
```js
croct.plug({
debug: true,
plugins: {
googleAnalytics: true,
}
});
```
2. Open your browser and check if there is an error like "Plugin 'pluginName' is not registered" in the console
1. If so, go over the previous points to double-check if you didn’t skip any step.
2. Otherwise, use one of our [support channels](https://github.com/croct-tech/plug-js#support) to get further assistance. We will be happy to help you.


46 changes: 24 additions & 22 deletions docs/user.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,28 +46,30 @@ This method creates a patch to apply changes to the user's profile.

These are the currently supported attributes:

| Attribute | Type | Constraints | Description
|----------------------|----------|-------------------------------------------------|-----------------------------------
| `firstName` | `String` | Between 1 and 50 characters long | The first name.
| `lastName` | `String` | Between 1 and 50 characters long | The last name.
| `birthDate` | `String` | Valid date in the form `YYYY-MM-DD` | The birth date.
| `gender` | `String` | Either `male`, `female`, `neutral` or `unknown` | The gender.
| `email` | `String` | Between 1 and 254 characters long | The email address.
| `alternateEmail` | `String` | Between 1 and 254 characters long | The alternate email address.
| `phone` | `String` | Between 1 and 30 characters long | The phone number.
| `alternatePhone` | `String` | Between 1 and 30 characters long | The alternate phone number.
| `address` | `object` | | The user address.
| `address.street` | `String` | Between 1 and 100 characters long | The address' street.
| `address.district` | `String` | Between 1 and 100 characters long | The address' district.
| `address.city` | `String` | Between 1 and 100 characters long | The address' city.
| `address.region` | `String` | Between 1 and 100 characters long | The address' region.
| `address.country` | `String` | Between 1 and 100 characters long | The address' country.
| `address.postalCode` | `String` | Between 1 and 20 characters long | The address' postal code.
| `avatar` | `String` | Well-formed URL | The personal avatar URL.
| `company` | `String` | Between 1 and 200 characters long | The company's name.
| `companyUrl` | `String` | Well-formed URL | The company's website URL.
| `jobTitle` | `String` | Between 1 and 50 characters long | The job title.
| `custom.*` | `object` | Up to 10 attributes | The map of custom attributes.
| Attribute | Type | Constraints | Description
|----------------------|----------|---------------------------------------------------|-----------------------------------
| `firstName` | `String` | Between 1 and 50 characters long | The first name.
| `lastName` | `String` | Between 1 and 50 characters long | The last name.
| `birthDate` | `String` | Valid date in the form `YYYY-MM-DD` | The birth date.
| `gender` | `String` | Either `male`, `female`, `neutral` or `unknown` | The gender.
| `email` | `String` | Between 1 and 254 characters long | The email address.
| `alternateEmail` | `String` | Between 1 and 254 characters long | The alternate email address.
| `phone` | `String` | Between 1 and 30 characters long | The phone number.
| `alternatePhone` | `String` | Between 1 and 30 characters long | The alternate phone number.
| `address` | `object` | | The user address.
| `address.street` | `String` | Between 1 and 100 characters long | The address' street.
| `address.district` | `String` | Between 1 and 100 characters long | The address' district.
| `address.city` | `String` | Between 1 and 100 characters long | The address' city.
| `address.region` | `String` | Between 1 and 100 characters long | The address' region.
| `address.country` | `String` | Between 1 and 100 characters long | The address' country.
| `address.postalCode` | `String` | Between 1 and 20 characters long | The address' postal code.
| `avatar` | `String` | Well-formed URL | The personal avatar URL.
| `company` | `String` | Between 1 and 200 characters long | The company's name.
| `companyUrl` | `String` | Well-formed URL | The company's website URL.
| `jobTitle` | `String` | Between 1 and 50 characters long | The job title.
| `interests` | `array` | Up to 30 strings between 1 and 30 characters long | The demonstrated interests.
| `activities` | `array` | Up to 30 strings between 1 and 30 characters long | The performed activities.
| `custom.*` | `object` | Up to 10 attributes | The map of custom attributes.

The following restrictions apply to custom attributes:

Expand Down

0 comments on commit 2c0174e

Please sign in to comment.