App Scripts
Zid Hybrid Apps: Javascript injection with Events supported
The Zid Hybrid Apps feature enables the injection of custom Javascript code directly into a merchant's storefront page. These scripts, operating on the client-side, pave the way for enhanced customer interaction. A recent enhancement introduces Events, allowing more granular interactions and tracking on the storefront.
This page covers the injection of Global scripts and Event-specific scripts.
App Scope
For your script to access the merchant store and inject the required events, the "Extra Addons" scope is necessary. Here's how to select it:
API Endpoints
Explore the full range of script-related API endpoints available in Zid to maximize the benefits of your scripting capabilities:
Implementation Cycle
- Kick-start your development.
- Create an App. Learn more here
- Request injection approval by contacting our team in Slack, or email: appmarket@zid.sa with your App name.
Once your app is published and we are confident in your injection and integration, we will recognize you as a trusted partner, thereby allowing you to bypass the manual approval process for future scripts.
Global and Customer (Global Object) Scripting
Our API provides two types of global objects for your use:
- Global: This script loads upon page initialization and may include any custom JS utility file from a third party that operates based on specific events.
- Customer (Global Object): This object contains details of the currently logged-in customer. If no user is logged in, this object remains empty. Please ensure your script can handle this scenario.
These global objects enable more complex interactions and provide the potential for enhancing your application's functionality. The Global script allows for the loading of JS utility files, extending the capabilities of your hybrid app. Similarly, the Customer (Global Object) permits a tailored customer experience based on the logged-in customer's details.
Customer (Global Object)
| Parameter | Description |
|---|---|
| window.customer | Contains details of the logged-in customer. If no user is logged in, this object will be empty. |
| Blueprint | Description |
|---|---|
| id | Customer ID |
| name | Customer Name |
| mobile | Customer Mobile |
| Customer Email |
Event Scripting
We provide a predefined set of events that you can tie your Javascript functions into. These events enable the execution of custom Javascript code upon certain storefront events. These events, while not customizable by partners, facilitate custom code execution upon their occurrence.
With Zid's system, you maintain a single script file containing all your Javascript functions for different events. The URL of this script file is submitted as part of the app-script object in an API request. Please note that the system currently doesn't return all fields of the app-script object in a GET request response, but this will be addressed in future updates.
Supported Events for Script Injection
Currently, the following Events are supported for Javascript injection:
- Purchase Event
- Product View Event
- Add to Cart Event
- Remove from Cart Event
- Start Checkout Event
Each event can trigger specific Javascript functions, enabling partners to track and interact with user actions in detail. For more information, please refer to the API reference and event-specific details in the following sections.
Event-Specific Parameters
Below is the list of event-specific parameters:
(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.)
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 |
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 |
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 |
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 |
Using the Zid API for Event-specific Scripting
Zid's API allows direct interaction with various components of the e-commerce platform. This proves particularly useful when dealing with Event-specific scripting, as the API can return complex data structures, such as a detailed representation of a shopping cart.
For example:
{
"id": 3180851825,
"session_id": "HR8XY3IyCNvs1aMKbHMMhzDfN9cKwPnl",
...
"sub_total_value": 29.96
}
This JSON object represents a shopping cart with one product, with each field providing detailed information about the cart and its contents.
You can interact with the API using cURL commands, or any other HTTP client. Here's a cURL command example to set up Event-specific scripts:
curl --location '<https://api.zid.sa/v1/managers/app-scripts>' \\
--header 'Accept: */*' \\
--header 'Accept-Language: ar' \\
--header 'Authorization: Bearer eyJ0e...0' \\
--header 'Content-Type: application/json' \\
--header 'User-Agent: Zid/1.113.00 (web)' \\
--header 'X-MANAGER-TOKEN: eyJpdiI6...=' \\
--form 'url="<https://raw.githubusercontent.com/gharbat/js-cs/main/test.js>"' \\
--form 'purchase_event="console.log(transactionItems)"' \\
--form 'product_details_event="console.log(productViewd)"' \\
--form 'add_to_cart_event="console.log(productCart)"' \\
--form 'remove_from_cart_event="console.log(productCart)"' \\
--form 'start_checkout_event="console.log(cart)"'
This command sets up different console log commands for each Event. Ensure to replace the placeholder values with your actual values.
In future enhancements, we plan to include more events, additional parameters, and increase the fields returned in the app-script object in GET requests. We welcome your feedback and suggestions for improvement.
For more details and discussions, join our Slack channel or contact us at appmarket@zid.sa.
Happy coding!