Reference Documentation for BilyPayload Data Type

Overview

This document describes the BilyPayload type used in systems requiring a comprehensive payload incorporating client data, order details, and product information. It's primarily utilized in contexts like user activity tracking, analytics, and data integration tasks.

BilyPayload Type Definition

BilyPayload consolidates multiple pieces of data about a user session or activity, potentially including client details, order information, and a list of products being interacted with.

Fields Description

| Field | Type | Optional | Description | | --------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------ | | client | Client | Yes | Details of the client involved in the transaction. | | order | Order | Yes | Order details, if applicable. | | products | Array | Yes | List of products involved in the transaction. | | pageTitle | string | Yes | The title of the page from which the payload is sent. | | userAgent | string | Yes | Browser or client identifier string. | | ip | string | Yes | IP address from which the session is initiated. | | referrer | string | Yes | Referring URL, if the user came from another site. | | sourceUrl | string | Yes | The URL of the page that initiated the payload. | | source | 'app' | 'web' | Yes | Indicates whether the payload comes from an app or web platform. | | searchQuery | string | Yes | Contains the search terms input by the user, reflecting the user's interests or immediate needs. | | category | string | Yes | Page category visited | | [key: string] | any | Yes | Allows for additional properties as needed for flexibility. |

Automatic Data Detection

• Fields such as pageTitle, userAgent, ip, referrer, and sourceUrl can be detected automatically by Bily tracking systems, especially in browser-based environments. These fields are optional when tracking via client devices and can be auto-populated to reduce manual data entry and ensure accuracy.

Client, Order, and Product Documentation

The BilyPayload utilizes several complex types that are documented separately:

• Client: Client Type Documentation
• Order: Order Type Documentation
• Product: Product Type Documentation

Implementation Guidelines

1. Automation and Flexibility:

   • Leverage Bily's capability to automatically detect certain fields to streamline data collection processes and reduce client-side scripting requirements.
   • Flexibly integrate additional data as needed with the [key: string]: any pattern for dynamic adaptation to varied business needs.

2. Data Integrity:

   • Validate data types and enforce quality checks before processing payloads to ensure that received data conforms to expected formats.

3. Integration with Existing Systems:

   • Seamlessly integrate BilyPayload into existing CRM, e-commerce platforms, or custom business applications using well-documented APIs and data handling protocols.

Example Usage

Here is how a minimal BilyPayload might be structured in a JSON format:

{
  "client": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "products": [
    {
      "id": "prod001",
      "name": "Wireless Keyboard",
      "price": 99.99,
      "currency": "USD",
      "quantity": 1
    }
  ]
}

Reference Documentation for User Data Type Management

Overview

This documentation details the data structures for managing personal and sensitive user information. Bily assures robust encryption of all sensitive data tracked, ensuring compliance with global data protection standards.

Data Encryption Policy

Bily is committed to encrypting all sensitive data, including data in transit and at rest, using industry-standard cryptographic methods.

Types of Data to be Encrypted:

• Personal identification information (e.g., names, emails, phone numbers).
• Demographic information (e.g., date of birth, gender).
• Location data (e.g., addresses).

Data Type Definitions

Address Type

Represents the postal address of a user or client, with all fields encrypted.

| Field | Type | Optional | Description | Encryption | | --------- | ------ | -------- | ------------------------------------------ | ---------- | | city | string | Yes | City or locality of the address. | Encrypted | | state | string | Yes | State, province, or region of the address. | Encrypted | | zip | string | Yes | Postal or ZIP code of the address. | Encrypted | | country | string | Yes | Country of the address. | Encrypted |

Client Type

Contains personal and contact details of a user, ensuring encryption of sensitive data.

| Field | Type | Optional | Description | Encryption | | ------------- | --------- | -------- | ---------------------------------------------- | ---------- | | firstname | string | Yes | First name of the client. | Encrypted | | lastname | string | Yes | Last name of the client. | Encrypted | | dateOfBirth | string | Yes | Date of birth in ISO 8601 format. | Encrypted | | email | string | Yes | Email address of the client. | Encrypted | | phone | string | Yes | Telephone number of the client. | Encrypted | | gender | string | Yes | Gender of the client. | Encrypted | | address | Address | Yes | Nested Address object with location details. | Encrypted |

Implementation Guidelines

1. Optional Fields:

All fields in the types are optional. Ensure that the application logic treats unspecified fields appropriately and provides graceful handling or defaults as necessary.

2. Validation:

• For email fields, implement standard email format validation.
• For phone fields, consider validating based on the international phone number format.
• For dateOfBirth, ensure the format is strictly verified and logically valid (e.g., not future-dated).

3. Security and Privacy:

Securely store sensitive information such as personal details, especially email, phone, and address.

4. Security and Privacy:

Respect privacy laws applicable to the user's data jurisdiction, such as GDPR in Europe or CCPA in California, which govern the handling of personal information.

Example Usage in API

Example JSON payload for creating a new client, demonstrating encryption:

{
  "client": {
    "firstname": "John",
    "lastname": "Doe",
    "dateOfBirth": "1990-05-15",
    "email": "[email protected]",
    "phone": "+1234567890",
    "gender": "male",
    "address": {
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "USA"
    }
  }
}

Reference Documentation for Product Data Type

Overview

This document outlines the structure for the Product data type, utilized in systems like e-commerce platforms, inventory management systems, and other applications that require detailed product information.

Product Type Definition

Describes the details of products, including identifiers, pricing, and classification.

Fields Description

| Field | Type | Optional | Description | | ---------- | ------ | -------- | ---------------------------------------------------------- | | id | string | No | Unique identifier for the product. | | name | string | No | Name of the product. | | price | number | No | Cost of one unit of the product. | | currency | string | No | Currency in which the price is expressed (e.g., USD, EUR). | | quantity | number | Yes | Number of units available or in the order. | | sku | string | Yes | Stock Keeping Unit; unique inventory identifier. | | category | string | Yes | Category of the product. | | brand | string | Yes | Brand of the product. | | image | string | Yes | URL or path to an image of the product. |

Implementation Guidelines

1. Required vs. Optional Fields:

   • Fields id, name, price, currency, and quantity are mandatory.
   • Fields sku, category, brand, and image are optional and should be included when relevant.

2. Validation:

   • ID: Ensure uniqueness.
   • Price: Must be a non-negative number.
   • Currency: Validate based on standard currency codes.
   • SKU: Should be unique if provided.
   • Image URLs: Should be valid and accessible.

3. API Use:

   • Secure endpoints that expose product data.
   • Include comprehensive API documentation outlining field values and examples.

Example Usage

An example JSON representation of a Product:

{
  "id": "prod123",
  "name": "Wireless Mouse",
  "price": 25.99,
  "currency": "USD",
  "quantity": 100,
  "sku": "WM12345",
  "category": "Electronics",
  "brand": "TechGadget",
  "image": "https://example.com/images/wireless-mouse.jpg"
}

Reference Documentation for Order Data Type

Overview

This document specifies the Order data type used for managing and recording transactions in systems such as e-commerce platforms, point of sale systems, and inventory management software. The structure captures all essential aspects of an order transaction.

Order Type Definition

The Order data type holds data related to a customer's order, including identification, total pricing, and product details included in the order.

Fields Description

| Field | Type | Optional | Description | | -------------- | -------------- | -------- | ------------------------------------------------------------------- | | id | string | No | Unique identifier for the order. | | total | number | Yes | The total cost of the order. | | currency | string | Yes | The currency in which the total cost is expressed (e.g., USD, EUR). | | products | Array | Yes | A list of products included in the order. | | tax | number | Yes | The value of payed taxes. | | shippingFees | number | Yes | The value of shipping fees. | | discount | number | Yes | Value of discount. | | discountCode | string | Yes | Used discount code. |

Details of Embedded Type Product

Refer to product data type documentation.

1. Order Validation:

   • Ensure the id is unique across the order management system.
   • Validate total to reflect the sum of products included, considering their price and quantity.
   • Confirm currency consistency across total and all Product prices, or implement accurate currency conversion methods.

2. Data Integrity:

   • Ensure that product details are accurate and correspond with the current catalog data at the time of the order.
   • Handle changes in product availability or price adjustments efficiently.

Example Usage

An example JSON representation of an Order:

{
  "id": "order123",
  "total": 299.99,
  "currency": "USD",
  "products": [
    {
      "id": "prod001",
      "name": "Bluetooth Keyboard",
      "price": 59.99,
      "currency": "USD",
      "quantity": 1,
      "sku": "BK987",
      "category": "Electronics",
      "brand": "KeyTech",
      "image": "https://example.com/images/keyboard.jpg"
    },
    {
      "id": "prod002",
      "name": "Wireless Mouse",
      "price": 24.99,
      "currency": "USD",
      "quantity": 2,
      "sku": "WM123",
      "category": "Electronics",
      "brand": "ClickPlus",
      "image": "https://example.com/images/mouse.jpg"
    }
  ]
}

Events types

| Event | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Search | User initiates a search, indicating interest or need for specific information, products, or services. | | Category Viewed | User browses a specific category, which could be a product category, content type, or service grouping. | | Product Viewed | User views details of a product, plan, or piece of content. Includes viewing pages for services or software features. | | Add to Wishlist | User saves items or content to a personal list for later review or purchase, applicable for products or saving content like articles or videos. | | View Wishlist | User reviews items or content saved in their wishlist, signifying ongoing interest. | | Remove from Wishlist | User removes items or content from their wishlist, indicating a change in preference or interest. | | Product Added | User adds a product, subscription plan, or paid content to their cart, showing intent to purchase or subscribe. | | Cart Viewed | User views their cart or list of intended purchases, reviewing chosen items before final actions. | | Remove from Cart | User removes an item from their cart, reflecting a change in decision regarding a potential purchase. | | Cart Updated | User changes the quantity or selection of items in the cart, adjusting their intended purchase details. | | Checkout Started | User begins the checkout process, indicating readiness to finalize a purchase or subscription. | | Payment Add Contact Info | User enters contact information during the checkout process, necessary for processing the transaction or for communication. | | Payment Add Shipping Info | User adds shipping information, relevant for physical goods delivery or geographical service personalization. | | Payment Add Address Info | User provides billing or service address details, crucial for invoicing and service provision. | | Payment Info Entered | User inputs payment details, a critical step towards transaction completion. | | Order Completed | User successfully completes an order or subscription, resulting in a transaction or engagement agreement. | | Subscription | User subscribes to a service or content platform, initiating a recurring relationship or continuous access. | | Subscription Updated | User modifies their subscription details or preferences, which may involve changing the plan level, altering features, or updating personal information. | | Subscription Cancelled | User terminates their subscription, ending their recurring access or membership. | | Subscription Renewed | User's subscription is automatically or manually renewed, extending their access and terms under the existing agreement. | | Order Updated | Changes made to an existing order post-purchase, which could involve modifications to subscriptions or service terms. | | Order Cancelled | User cancels an order or subscription, discontinuing the purchase or service relationship. | | Newsletter | User subscribes to a newsletter, indicating interest in regular updates, news, or promotional content. | | Lead | User shows potential interest in a service or product, often through a form submission or a trial request, initiating a sales lead. | | Contact Form Submitted | User submits a query or feedback via contact forms, important for user support and engagement. | | Login | User logs into their account, initiating access to personalized services, content, or account management. | | Logout | User logs out of their account, ending their current session securely. |