plugins/browser-plugin-snowplow-ecommerce/src/types.ts
import { CommonEventProperties, SelfDescribingJson } from '@snowplow/tracker-core';
/**
* Type/Schema for an ecommerce Action
*/
export interface Action {
/**
* Standard ecommerce actions
*/
type:
| 'add_to_cart'
| 'remove_from_cart'
| 'product_view'
| 'list_click'
| 'list_view'
| 'promo_click'
| 'promo_view'
| 'checkout_step'
| 'transaction'
| 'refund'
| 'trns_error';
/**
* You can add a name for the list presented to the user.
* E.g. product list, search results, shop the look, frequently bought with
*/
name?: string;
}
/**
* Type/Schema for a checkout_step event in Ecommerce
*/
export interface CheckoutStep {
/* Checkout step index */
step: number;
/* Shipping address postcode */
shipping_postcode?: string;
/* Billing address postcode */
billing_postcode?: string;
/* Full shipping address */
shipping_full_address?: string;
/* Full billing address */
billing_full_address?: string;
/* Can be used to discern delivery providers DHL, PostNL etc. */
delivery_provider?: string;
/* Store pickup, standard delivery, express delivery, international */
delivery_method?: string;
/* Coupon applied at checkout */
coupon_code?: string;
/* Selection of 'existing user' or 'guest checkout' */
account_type?: string;
/* Any kind of payment method the user selected to proceed. Card, PayPal, Alipay etc. */
payment_method?: string;
/* Invoice or receipt */
proof_of_payment?: string;
/* If opted in to marketing campaigns to the email address */
marketing_opt_in?: boolean;
}
/**
* Type for a cart entity in Ecommerce
*/
export interface Cart {
/**
* The unique ID representing this cart
*/
cart_id?: string;
/**
* The total value of the cart after this interaction
*/
total_value: number;
/**
* The currency used for this cart (ISO 4217)
*/
currency: string;
/**
* Array of products added/removed from cart
*/
products?: Product[];
}
/**
* Type/Schema for a page entity in Ecommerce
*/
export interface Page {
/**
* The type of the page that was visited (e.g. homepage, product page, cart,checkout page, etc)
*/
type: string;
/**
* The language that the web page is based in
*/
language?: string;
/**
* The locale version of the site that is running
*/
locale?: string;
}
/**
* Type/Schema for a product entity in Ecommerce
*/
export type Product = {
/**
* The SKU or product ID
*/
id: string;
/**
* The name or title of the product
*/
name?: string;
/**
* The category the product belongs to.
* Use a consistent separator to express multiple levels. E.g. Woman/Shoes/Sneakers
*/
category?: string;
/**
* The price of the product at the current time.
*/
price: number;
/**
* The recommended or list price of a product
*/
list_price?: number;
/**
* The quantity of the product taking part in the action. Used for Cart events.
*/
quantity?: number;
/**
* The size of the product
*/
size?: string;
/**
* The variant of the product
*/
variant?: string;
/**
* The brand of the product
*/
brand?: string;
/**
* The inventory status of the product (e.g. in stock, out of stock, preorder, backorder, etc)
*/
inventory_status?: string;
/**
* The position the product was presented in a list of products (search results, product list page, etc)
*/
position?: number;
/**
* The currency in which the product is being priced (ISO 4217)
*/
currency: string;
/**
* Identifier/Name/Url for the creative presented on a list or product view.
*/
creative_id?: string;
};
/**
* Type/Schema for a promotion entity in Ecommerce
*/
export interface SPPromotion {
/**
* The ID of the promotion.
*/
id: string;
/**
* The name of the promotion.
*/
name?: string | null;
/**
* Array of SKUs or product IDs showcased in the promotion.
*/
product_ids?: string[] | null;
/**
* The position the promotion was presented in a list of promotions E.g. banner, slider.
*/
position?: number | null;
/**
* Identifier/Name/Url for the creative presented on the promotion.
*/
creative_id?: string | null;
/**
* Type of the promotion delivery mechanism. E.g. popup, banner, intra-content
*/
type?: string | null;
/**
* The website slot in which the promotional content was added to.
*/
slot?: string | null;
}
/**
* Type/Schema for a transaction entity in Ecommerce
*/
export interface SPTransaction {
/**
* The ID of the transaction
*/
transaction_id: string;
/**
* The total value of the transaction
*/
revenue: number;
/**
* The currency used for the transaction
*/
currency: string;
/**
* The payment method used for the transaction
*/
payment_method: string;
/**
* Total quantity of items in the transaction
*/
total_quantity?: number;
/**
* Total amount of tax on the transaction
*/
tax?: number;
/**
* Total cost of shipping on the transaction
*/
shipping?: number;
/**
* Discount code used
*/
discount_code?: string;
/**
* Discount amount taken off
*/
discount_amount?: number;
/**
* Whether the transaction is a credit order or not
*/
credit_order?: boolean;
/**
* Array of products on the transaction from cart
*/
products?: Product[];
}
/**
* Type/Schema for a refund entity in Ecommerce
*/
export interface Refund {
/**
* The ID of the transaction.
*/
transaction_id: string;
/**
* The currency in which the product is being priced (ISO 4217).
*/
currency: string;
/**
* The monetary amount refunded.
*/
refund_amount: number;
/**
* Reason for refunding the whole or part of the transaction.
*/
refund_reason?: string | null;
/**
* Array of products on the refund. This is used when specific products are refunded.
* If not present, the whole transaction and products will be marked as refunded.
*/
products?: Product[];
}
/**
* Type/Schema for a transaction error entity in Ecommerce
*/
export interface TransactionError {
/**
* Error-identifying code for the transaction issue. E.g. E522
*/
error_code?: string;
/**
* Shortcode for the error occurred in the transaction. E.g. declined_by_stock_api, declined_by_payment_method, card_declined, pm_card_radarBlock
*/
error_shortcode?: string;
/**
* Longer description for the error occurred in the transaction.
*/
error_description?: string;
/**
* Type of error.
* Hard error types mean the customer must provide another form of payment e.g. an expired card.
* Soft errors can be the result of temporary issues where retrying might be successful e.g. processor declined the transaction.
*/
error_type?: 'hard' | 'soft' | null;
/**
* The resolution selected for the error scenario. E.g. retry_allowed, user_blacklisted, block_gateway, contact_user, default
*/
resolution?: string;
/**
* The transaction object representing the transaction that ended up in an error.
*/
transaction: SPTransaction;
}
/**
* Type/Schema for an user entity in Ecommerce
*/
export interface User {
/**
* The user ID
*/
id: string;
/**
* Whether or not the user is a guest
*/
is_guest?: boolean;
/**
* The user's email address
*/
email?: string;
}
export interface CommonEcommerceEventProperties<T = Record<string, unknown>> extends CommonEventProperties<T> {
/** Add context to an event by setting an Array of Self Describing JSON */
context?: Array<SelfDescribingJson<T>>;
}
export type ListViewEvent = { name: string; products: Product[] };
export type ListClickEvent = { name: string; product: Product };