Skip to main content

Custom-built website integration

Updated over a week ago

Overview

This guide walks you through the process of integrating WorkMagic with your custom e-commerce website. By completing this integration, you will enable seamless tracking of customer interactions and order placements, ensuring precise reporting and attribution.

To complete the integration, you will need to complete:

  1. Store Information: Setup account-level details, including store domain, currency, and timezone.

  2. Pixel SDK installation: Install the WorkMagic Pixel SDK on your website to accurately capture customer interaction. Ensure that the Pixel SDK is installed on every page of your store for accurate tracking across all customer interactions.

  3. Orders API integration: Integrate the Orders API to enable WorkMagic to capture order and sales data, linking customer actions to specific orders for detailed analysis.

  4. Checkout match ratio: Verify that both the Pixel SDK and Orders API are integrated correctly to ensure accurate data capture and reporting.

This process ensures that your account is fully set up for optimal tracking, data management, and attribution analysis.

Steps to Complete Integration:

Step 1: Complete Store Information

There are two ways to complete store informations:

1. Via Onboarding Step 2, select "custom built website" as Primary Sales Channel.

2. Via Setting Page: If you haven't connect the primary sales channel thru onboarding, it's also accessible via Settings > Sales Channel

  1. Complete your store information:

    1. Domain

    2. Currency

    3. Time Zone

    4. Upload Store Logo (Optional)

  2. Click "Confirm" button to verify the domain and complete the process.

  3. You will see the "Completed" tag on the store information via Onboarding step.

Once your store domain, currency and time zone are confirmed and verified as valid, you can no longer change them any more. To update them, you’ll need to contact us.

Step 2: WorkMagic Pixel installation

2.1. Pixel SDK Installation Instructions

There are two ways to install WorkMagic pixels: manually install them on the store website or insert them into Google Tag Manager.

Option 1: Install manually on all pages

  • Just click Copy button

  • Install the pixel manually by inserting a Javascript Code snippet in front of the </head> tag on all pages

<script src="https://fe-assets.workmagic.io/pixel/latest/wm.min.js" crossorigin="anonymous"></script> <script> ;(function (h) { h.WorkmagicPixel.init({ tenantId: '150040', tenantIdSign: 'v1_86ff440111b0c218a8cb2f779feabc8884b93089', source: 'custom-built-website', }); })(window); </script>

Option 2: Install with Google Tag Manager

If you use GTM to manage pixel scripts, you can add WorkMagic pixel scripts in the following way:

Scripts content

<script src="https://fe-assets.workmagic.io/pixel/latest/wm.min.js" crossorigin="anonymous"></script> <script> ;(function (h) { h.WorkmagicPixel.init({ tenantId: '150040', tenantIdSign: 'v1_86ff440111b0c218a8cb2f779feabc8884b93089', source: 'custom-built-website', isGtm: true, }); })(window); </script>

  1. In GTM https://tagmanager.google.com/#/home, create a new Tag.

  2. Select "Custom HTML."

  3. Copy the code provided on the Pixel installation page, and paste the code into the script area.

  4. Select the "All pages" trigger.

  5. Name the tag, and click "Save".

2.2. Pixel SDK event tracking

Page viewed reporting

After installing the Pixel SDK, page view data will be automatically reported. Ensure that the Pixel SDK is installed on every page of your store for accurate tracking across all customer interactions.

Checkout started reporting

The event should be reported after the order is generated and before initiating the checkout process. Ensure that checkout.token of pixel matches the checkout_token of the order.

Event name: checkout_started

Event parameters：

Parameters

Type

Required

Pattern/Enum

checkout

token

string

Y

A unique identifier for a single checkout session, ensuring it matches the checkout_token in the Order API. If the unique identifier is not available, the order_id (if already exists) can be used as the checkout_token.

Ensure uniqueness: The checkout.token in each event must be unique, with no two orders sharing the same token. Maximum length: 40 characters.

Example:

window.WorkmagicPixel("checkout_started", { checkout: { token: "xxxx" } });

2.3. Pixel SDK verification

Option 1: Use WorkMagic's testing tool

  • Onboarding > Store data > WorkMagic Pixel Installation > "Test Pixel"

  • Setting > Pixel Setting > scroll down to "Debug Tools" > click "Check"

Option 2: Use debug mode

When integrating the SDK, enable debug mode to easily monitor the SDK's operation. Please enable debug mode only for testing during development. It is not recommended to enable debug mode in the production environment.

<script src="https://fe-assets.workmagic.io/pixel/latest/wm.min.js" crossorigin="anonymous"></script> <script> ;(function (h) { h.WorkmagicPixel.init({ // other params debug: true }); })(window); </script>

You can view the Pixel trigger details in the debug console.

Once you see the event data, you will see the "completed" tag on Onboarding or on pixel setting

Step 3: Order & Sales data integration

3.1. How to generate API Key

By default, one API Key has already been generated. You can directly use it by copying the API Key. You can have multiple API Keys by generating them using the method below:

  • Option 1: Via Onboarding step 2 -> Store data > Order API Integration > Generate new API key

  • Option 2: Find API Key in Settings > Pixel Setting > Custom-built website > Scroll down to Orders API integration > Generate new API Key

3.2. Instructions

  1. API domain: https://store-api.workmagic.io/api/orders

  2. Account Authentication: Use the Header X-API-KEY as the unified authentication method. The X-API-Key can be found in WorkMagic Settings (support generate new API key).

  3. Response Codes: Use HTTP Status Codes as the unified status indicators.

    • 200: Success

    • 400: Invalid parameters. Please check if required fields are missing or if field types are correct.

    • 401: Invalid API KEY. Please contact the developer.

    • 500: Internal server error. Please contact the developer.

  4. Example:

    1. Request:

      curl -v https://store-api.workmagic.io/api/orders \ --header 'X-API-KEY: mstak_ex5mk5fddybxbhj8c3dxnmry8pcsp3z3'

    2. Response:

      # HTTP/2 200 { "orders": [ ... ] }

3.3. Upload Order data

  • Instruction: Upload order data to Workmagic. Both new and updated orders should be submitted via this API. When updating an order, the data with the same order_id will be overwritten with the new information.

  • API: POST https://store-api.workmagic.io/api/orders

  • API fields:

When developing integration, please refer to this API documentation at https://developer.workmagic.io/reference/postapiorders as the source of truth.

The table below is just for for a quick glance, as it's not updated regularly.

  • Example:

  1. Request:

    curl -v https://store-api.workmagic.io/api/orders \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: mstak_ex5mk5fddybxbhj8c3dxnmry8pcsp3z3' \ --data '{ "orders": [ { "id": "8f698a21-1801-4513-80e1-2ccab2c82cf1", "created_at": "2025-01-01T00:00:00-08:00", "updated_at": "2025-01-01T00:00:00-08:00", "browser_ip": "216.191.105.146", "order_number": "10001", "landing_site": "http://www.example.com?source=abc", "referring_site": "http://www.example.com", "checkout_token": "bd5a8aa1ecd019dd3520ff791ee3a24c", "financial_status": "paid", "total_price": 10.01, "current_total_price": 10.01, "subtotal_price": 10.01, "current_subtotal_price": 10.01, "current_total_discounts": 10.01, "current_total_tax": 10.01, "line_items": [ { "id": "8f698a21-1801-4513-80e1-2ccab2c82cf1", "product_id": "80d29248-761b-480f-82cb-c202201c5ea9", "variant_id": "7a38ee09-0a24-49cb-81e0-67c5ceb6da59", "title": "IPod Nano", "price": 10.01, "quantity": 1, "current_quantity": 1 } ], "customer": { "id": "5f098331-996d-4135-a103-d2300e64c029", "email": "[email protected]" }, "shipping_address": { "zip": "T0E 0M0", "city": "Drayton Valley", "country": "Canada", "country_code": "CA" }, "extensions": { "order_app_name": "Online store", "order_cost_cogs": 10.01, "order_cost_handling": 10.01, "order_cost_shipping": 10.01, "order_cost_transaction": 10.01, "order_refund_amount": 10.01, "order_refund_product_count": 10, "is_refund_order": false, "is_subscription_order": true, "is_new_customer_order": true, "previous_order_create_time": "2025-01-01T00:00:00-08:00", "customer_order_serial_number": 1 } } ] }'

  2. Response:

    # HTTP/2 200 { "orders": [ ... ] }

3.4. Order Data verification

This step provides guidance to verify that the Orders API and Pixel SDK are integrated correctly, with the checkout events reported by the Pixel SDK using a consistent identifier (checkout token) to link them to the corresponding orders.

Option 1: Use WorkMagic's testing tool

  • Via Onboarding > Store data > Order API Integration > Check Status > Test Orders API

  • Via Settings > Pixel settings > Custom-built website > Order API integration > Check order data Accuracy

Option 2: Use API to pull data for verification

  • Instruction: Query the latest 100 orders uploaded in the last 72 hours for data verification. Compare this data with your store's records to ensure complete consistency, aiming for a full match between the orders received by WorkMagic and your store's records.

  • API: GET https://store-api.workmagic.io/api/orders

If there are any discrepancies, refer to the API documentation at https://developer.workmagic.io/reference/getapiorders as the source of truth.

  • Example:

    • Request:

      curl -v https://store-api.workmagic.io/api/orders \ --header 'X-API-KEY: mstak_ex5mk5fddybxbhj8c3dxnmry8pcsp3z3csp3z3'

    • Response:

      # HTTP/2 200 { "orders": [ ... ] }

Once completed, you will see the "Completed" tag on Onboarding or "Connected" tag on Pixel Setting.

Step 4: Checkout match ratio

  • Instruction: Measure the match ratio between pixels and orders within the past 72 hours. The goal is to achieve a match ratio close to 100% for all orders originating from web pages. The match ratio is calculated as: Match Ratio = Matched Orders / Total Orders

  • If the match ratio is 0: It indicates an error in the checkout.token of the pixel's "checkout_started" event or the checkout_token in the order data.

  • If the match ratio is low: This may suggest that some web pages are missing the Pixel SDK.

  • Ensure uniqueness: The checkout_token in each order must be unique, with no two orders sharing the same token.

Option 1: Use WorkMagic's testing tool

Onboarding Step 4 > Test Checkout token match ratio

Option 2: Use API to verify checkout match ratio

Note: Currently, this API takes about one minute to respond.

  1. API: GET https://store-api.workmagic.io/api/statistics If there are any discrepancies, refer to the API documentation at https://developer.workmagic.io/reference/getapistatistics as the source of truth.

  2. Example:

    1. Request:

      1. curl -v https://store-api.workmagic.io/api/statistics \ --header 'X-API-KEY: mstak_ex5mk5fddybxbhj8c3dxnmry8pcsp3z3'

    2. Response:

      1. # HTTP/2 200 { "statistics": { "time_range": ["2025-01-07T00:00:00Z", "2025-01-09T23:59:59Z"] "page_viewed_event_count": 10000, "checkout_started_event_count": 1000, "created_order_count": 1000, "checkout_matched_order_count": 500, "match_ratio": 0.5, } }

Did this answer your question?