App Scripts

Zid App scripts provide the capability to inject custom JavaScript directly into a merchant's storefront, enabling dynamic user interactions and tailored experiences.

This documentation outlines the process of injecting global scripts and implementing event-specific scripts that respond to user actions in real-time.

Global and Customer Object Scripting

Zid’s API supports two types of global objects for advanced scripting:

1. Global Object: Loads upon page initialization and can include custom JS utility files.
2. Customer Object: Contains details of the currently logged-in customer. If no user is logged in, the object remains empty.

Global Object Parameters:

Parameter	Description
window.customer	Contains details of the logged-in customer. Empty if no user is logged in.

Customer Object Blueprint:

Parameter	Description
id	Unique identifier for the customer
name	Full name of the customer
mobile	Mobile number of the customer
email	Email address of the customer

These global objects enable dynamic interactions and personalized user experiences.

Event-Driven Scripting

Zid’s platform allows for event-driven scripting, enabling the execution of JavaScript in response to specific storefront events.

Supported Events:

1. Purchase Event
2. Product View Event
3. Add to Cart Event
4. Remove from Cart Event
5. Start Checkout Event

Each event can trigger specific JavaScript functions to track and interact with user actions.

:::info[]
(Please note that productCart refers to the product in the cart, and productViewd refers to the viewed product. The unconventional spelling is consistent with the codebase.)
:::

1. Purchase Event

Parameter	Description
transactionItems	List of products the user purchased.
id	Order Id
product id	Product Id
name	Product Name
sku	Product Sku code
category	Product Category Name
price	Product Price
quantity	Product Quantity
currency	currency
total	Product Total

2. Product View Event

Parameter	Description
productViewd	Single product details object.
id	Product Id
name	Product Name
category	Product Category Name
price	Product Price
position	Display Order

3. Add to Cart Event

Parameter	Description
productCart	Single product cart object.
id	Product Id
name	Product Name
category	Product Category Name
price	Product Price
position	Display Order
list	Name of page
quantity	Product Quantity

4. Remove from Cart Event

Parameter	Description
productCart	Single product cart object.
id	Product Id
name	Product Name
category	Product Category Name
price	Product Price
position	Display Order
list	Name of page
quantity	Product Quantity

5. Start Checkout Event Parameters

Parameter	Description
cart_id	Unique identifier for the shopping cart.
cart_total	Total value of the cart.
currency	Currency used for the transaction.
items	List of items in the cart, each represented by its own object.
item_id	Unique identifier for each product in the cart.
item_name	Name of the product.
item_price	Price of the product.
item_quantity	Quantity of the product in the cart.
item_category	Category of the product.
user_id	Unique identifier of the user (if logged in).
session_id	Unique identifier for the session (if user is not logged in).
cart_discount	Any discount applied to the cart.
shipping_cost	Estimated shipping cost for the cart.
checkout_step	Current step in the checkout process (e.g., shipping, payment, confirmation).
payment_method	Selected payment method (if chosen).

Utilizing Zid API for Event-Specific Scripting

Zid’s API allows direct interaction with the platform’s components, facilitating the implementation of event-specific scripts.

Example: JSON Representation of a Shopping Cart

{
  "id": 3180851825,
  "session_id": "HR8XY3IyCNvs1aMKbHMMhzDfN9cKwPnl",
  "sub_total_value": 29.96,
  "items": [
    {
      "product_id": "12345",
      "name": "Product Name",
      "quantity": 2,
      "price": 14.98
    }
  ]
}

cURL Command Example:

curl --location 'https://api.zid.sa/v1/managers/app-scripts' \
--header 'Accept: */*' \
--header 'Accept-Language: ar' \
--header 'Authorization: Bearer <your_token_here>' \
--header 'Content-Type: application/json' \
--header 'User-Agent: Zid/1.113.00 (web)' \
--header 'X-MANAGER-TOKEN: <your_token_here>' \
--form 'url="https://yourdomain.com/your-script.js"' \
--form 'purchase_event="console.log(transactionItems)"' \
--form 'product_details_event="console.log(productViewed)"' \
--form 'add_to_cart_event="console.log(productCart)"' \
--form 'remove_from_cart_event="console.log(productCart)"' \
--form 'start_checkout_event="console.log(cart)"'

Replace placeholder values with your actual data.

Getting Started with Script Injection

1. App Scope and Permissions

To inject scripts into a merchant's storefront, your app must have the appropriate permissions. Specifically, the "Extra Addons" scope must be enabled.

Steps to Enable the "Extra Addons" Scope:

1. Access the app settings in the Zid Developer Dashboard.
2. Navigate to the "Permissions" section.
3. Select the "Extra Addons" scope to grant the necessary permissions for script injection.

2. Use API for Script Management

Zid offers a variety of API endpoints to help you manage your scripts efficiently:

• Create Script: Initiate a new script injection.
• Retrieve Scripts: Get a list of all scripts associated with a store.
• Update Script: Modify an existing script.
• Delete Script: Remove a script that is no longer needed.

3. Request Injection Approval

After your hybrid app is ready, reach out to our team for script injection approval through the dashboard chat widget or via email at appmarket@zid.sa. Once you've achieved trusted partner status, future scripts will be automatically injected without the need for approval.

:::info[]
We're expanding supported events and improving API responses. Your feedback is key — share your ideas to help us enhance the platform!
:::