Skip to main content

Tutorial | SDK Web Behavior Tracking Tool

  • Updated

    Crescendo SDK (Web SDK) provides real-time website behavior tracking, helping brands instantly collect interaction data from visitors and members on their website or e-commerce platform. This data can then be used as the foundation for retargeting, automated messaging, and personalized engagement.

    Due to privacy policies and platform limitations, brands often cannot access Google Analytics 4 (GA4) behavioral data in real time or in full. With Crescendo SDK, brands can receive key behavioral events instantly without relying on GA4 reporting latency, improving the timeliness of marketing and customer engagement.

    Key Features

    Crescendo SDK provides the following key capabilities:

    • Receive website behavior events in real time to avoid missing engagement opportunities due to GA4 data latency
    • Supports common website and e-commerce events, including but not limited to: 
      • Page view
      • Product view
      • Add to cart
      • Begin checkout
      • Purchase
    • [New Feature] User Identification (Identify): Enables the explicit reception and binding of specific identity information, such as a member ID (customerId) or email, after a visitor logs in or registers. This facilitates automatic cross-device tracking and identity resolution.  (Currently applicable only to self-hosted e-commerce clients)

    Serves as the behavioral data source for MAAC and CAAC related features, enabling downstream automation and retargeting use cases.

    Who This Is For

    This feature is suitable for:

    Brands with a website or e-commerce site that want to track user behavior
    Customers using MAAC Growth plan or above, or CAAC Starter plan or above
    Teams with engineering/technical resources to help complete SDK or tracking code setup

    Compatible Features

    After installing and configuring the SDK, it can be used with the following Crescendo features:

    Important Notes

    • SDK installation, configuration, and tracking code implementation must be completed by the brand on their website or e-commerce platform.
    • Installation steps vary by website type (self-hosted website, e-commerce platform, Shopify, 91APP). Please follow the corresponding setup flow in the sections below.
    • Do not use multiple event sources at the same time (e.g., GA4 dataLayer and Event Tracking API) to avoid duplicate event records.

    Setup Steps

    Step 1: Get Your Dedicated SDK Code

    You can obtain your dedicated SDK code in Admin Center.

    This code will be used later for installation via GTM, your website, or your e-commerce platform.

    1. Go to Admin Center
      • MAAC > Extension Marketplace > Admin Center 
      • CAAC > Settings > Organization Management > App Center 
    2. Admin Center > Channel Settings > Add Channel 
    3. Select Website > Continue
    4. Channel Settings > Edit 
    5. Channel Settings > Web Tools > Turn on the items you want to install
    6. Click Install > Enter your domain and select the e-commerce platform type
    7. Copy your dedicated SDK code

    Step 2: Install via Google Tag Manager (GTM) (For Some Website Types)

    For the following website types, the brand needs to install via Google Tag Manager:

    • Self-hosted website
    • SHOPLINE
    • CYBERBIZ

    For the following website types, the brand does not need to set up GTM by themselves:

    • Shopify (use the Shopify-specific SDK installation method)
    • 91APP (setup assisted by Crescendo)

    GTM Setup Includes These Main Steps

    1. Configure the Trigger

      1. Click New > Trigger Configuration


         
      2. Select trigger type: DOM Ready
      3. Name the trigger > Choose All DOM Ready Events > Save

    2. Configure the Tag
      1. Click New Tag

         
      2. Name the tag (e.g., Crescendo SDK)
      3. Click Tag Configuration

         
      4. Select Custom HTML

         
      5. Paste your Crescendo SDK code into the HTML field

         
      6. Set the trigger to DOM Ready


         
      7. Click Save

         

    3. Click Submit in the top-right corner

       
       

      1. In the “Submit Changes” panel, choose Publish

         
      2. You may be asked to add a container version description. You can skip it.

         

    4. Note your GTM container ID and configure it on your website or e-commerce platform.

    Installation Guide by Website Type

    Self-hosted Website: SDK Installation

    Option 1: Send Events via GA4 Data Layer (Recommended)

    This option applies to websites that have Google Analytics 4 (GA4) implemented.

    Follow the format in Google Analytics 4 (GA4) recommended events and write event data into the Google data layer , ensuring the event structure meets GA4 specifications.

    1. Transmitting Standard E-commerce Behavioral Events
      Commonly supported GA4 recommended events include (but are not limited to)

    • view_item

    • add_to_cart

    • remove_from_cart

    • begin_checkout

    • purchase

       

    1. [New Feature] Transmitting User Identification Events (Identify)  (Currently applicable only to self-hosted e-commerce clients)

    To precisely link a visitor's website behavior with your actual customer data, please ensure you trigger the clIdentity event at key touchpoints such as "successful login," "registration completed," or "form submitted." 

    💻 Developer Implementation Guide: Please embed the following tracking code into your frontend's callback function that handles successful logins or registrations. 

    The exact moment your backend successfully authenticates the user's credentials and the frontend retrieves their member data (such as Member ID or Email), push this information using window.dataLayer.push.

    (💡 Note: This is a non-blocking call and will not impact your website's normal performance.)

    // Triggered upon successful user login or registration
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: 'clIdentity',
  params: {
    customerId: 'M0012345',      // Required: Unique platform member ID (Primary Identity Key)
    email: 'user@example.com',    // Optional: User email (Secondary Identity Key)
    name: 'Wang Xiao-Ming',       // Optional: User name
    phone: '+886912345678',      // Optional: Phone number, preferably in E.164 format (including country code)
    birthday: '1995-01-01',      // Optional: Date of birth, format must be YYYY-MM-DD
    gender: 'male'               // Optional: Gender, supports male / female / other
  }
});

    1. Use the DataLayer Plugin to Convert Custom Event Formats

    Crescendo provides a DataLayer Plugin (clPluginDataLayer) that supports a custom data transformation function (parse). This helps you convert existing Data Layer event payloads into a system-recognizable format before sending.

    How it works

    • clPluginDataLayer accepts a parse function to process event data whenever an event occurs
    • If parse is not provided, the system processes events using the default Data Layer format
    • The input of parse is the original event payload, and the output must match the system-expected structure

    Example

    The example below shows how to convert GA4 ecommerce event data to the expected format before sending:

    clPluginDataLayer({
 parse: (data) => {
   const item = Array.isArray(data) && data.length > 0 ? data[0] : data;
   if (
     item &&
     typeof item === "object" &&
     !Array.isArray(item) &&
     "event" in item &&
     "ecommerce" in item
   ) {
     const obj = item;
     // Convert the payload to the expected structure
     // "0" is always "event"
     // "1" is the event name
     // "2" is the payload sent to the backend
     const result = [
       {
         "0": "event",
         "1": obj.event,
         "2": obj.ecommerce,
       },
     ];
     return result;
   }
   return item;
 },
});

    Option 2: Send Events Directly via Crescendo Event Tracking API

    This option applies to scenarios where GA4 is not used or where you need to control event sending logic yourself. ( Event Tracking API )

    Setup steps:

    • Implement Crescendo Web SDK on your website
    • We recommend installing Web SDK via Google Tag Manager (GTM)
    • If GTM cannot be used, have your IT team install the Web SDK directly in the website source code

    Option 3: Embed Web SDK

    How to Confirm the SDK Is Working

    Web Chat Widget

    • Check 1: In Admin Center, select Check Connection 
    • Check 2: Send a message in the Web Chat Widget and verify that the message is received in CAAC

    Web Tracking

    • Check 1: Confirm whether the page_view event is received
      • When a user visits your website, Crescendo SDK will send a page_view event.
      • Please contact Crescendo Lab Customer Success to confirm whether the page_view event is received.
      • If it is not received, the SDK is not installed correctly. Please check with your technical team or platform provider.
    • Check 2: The expected event (e.g., add-to-cart) is not received
      • Please contact Crescendo Lab Customer Success to confirm whether the specific event is received.
      • If it is not received, the SDK may not be installed correctly. Please check with your technical team or platform provider.

    🔧 FAQ

    Q: Why is the Web Chat Widget still not showing on my website after I installed and configured the SDK?

    A: Please click the help widget in the bottom-right corner to contact support. If you are using a self-hosted website, please provide a screenshot showing the SDK code placement. If you are using GTM, please provide screenshots of your “Trigger” and “Tag Configuration” settings.

    Q: Will calling Identify (clIdentity) multiple times result in duplicate user profiles? 

    A: No. When the call is repeated, the system updates the data following the "new overwrites old" principle while "ignoring null values." For example, if the current call does not include an email address, the SDK will not clear the user's previously existing email record. Therefore, duplicate profiles will absolutely not be created.

    Q: If the Identify call fails, will it cause the website to crash or affect core functionalities? 

    A: No. This event invocation is non-blocking. Even if the call fails, it will not disrupt normal website operations. Developers may implement a try-catch block to log any errors independently.

    Q: Can the customerId be modified after it has been transmitted? 

    A: It is strongly recommended not to modify it. The customerId serves as the primary identifier (Primary Key) for a user's identity. Modifying it will prevent the successful association of the user's past historical behavioral data.

    Related articles