Apps: Web Data Collection: Building Blocks

A building block is a component needed for building an Event. The building blocks are located in the menu in the left sidebar in the rule editor, separated into the groups; Segment Conditions, Triggers, Conditions and Event data.

To make an Event, drag and drop the building blocks into the area with the corresponding color.

If there is a behavior you cannot track with our current building blocks, you have the option to create new building blocks. This is an advanced feature for developers. Contact your company administrator if you want to add such a feature.


Further reading:

For more information about "Building blocks".




A building block is a component needed for building an Event. The building blocks are located in the menu in the left sidebar in the rule editor, separated into the groups; Segment Conditions, Triggers, Conditions and Event data.


If there is a behavior you cannot track with our current building blocks, you have the option to create new building blocks. This is an advanced feature for developers.


If you want detailed help on different aspects of Building Blocks go to the Building Blocks area in the Knowledge Base. This is part of the Web Data Collection app.


Interface:

  • Toolbar
  • Used arguments area
  • Argument’s repository
  • Code editor
  • Advanced options

1. Toolbar

It contains the main settings of a building block. Here you can save, copy or delete the Building block (BB). Or change the name, description and category, either by using the gear-icon in the control group on the right side, or clicking directly on the option you want to change on left.


2. Arguments area.

Arguments listed here will be used in building block to pass data and will be shown in inspector in event builder. To add new argument, you need to drag-n-drop it from argument’s repository.


3. Type of building block

Before creating the building block, you need to decide of which type it should be. There are three types of building blocks: trigger, value and condition.


4. Code editor

The editor of the building block code consists of two parts:

  • The text area for writing the code.
  • Arguments shortcut’s bar - contains the links to quick insert the arguments into the code. Arguments are highlighted in code with yellow background.


5. Arguments type repository

All possible types of arguments are listed here. They are used to drag-n-drop to arguments area. Meaning of each type will be described below.


6. Advanced options

Advanced settings are used for more precise adjustment of building block such as cost of execution (affect the order of executing), title template (what should be shown on BB box in event editor), description, result type, etc. It’s highly recommended to change this settings carefully. Better to leave it for advanced users.


7. Inspector

Window which is showing in event editor used to set all defined arguments.


Steps to create new building block

Building block types

  • Trigger - describes the action on which the event should be triggered. Must contain rule.trigger() in order to fire the event. In a common case actions like page load or click on specific element.
  • Value - contains the data available on that page or in this event. The data can be got from page source, cookie, localstorage, profile cloud or even calculated dynamically. Result can be passed to another Value or Condition. Also can just execute the code without returning anything, in that case it couldn’t be used in conditions or other values.
  • Condition - used to define the circumstances under which the event will trigger. Usually used to compare values to each other, to static data or check it existence. Also could be used to set limitations like trigger event once per page, session, etc. Need to return either true or false.

Arguments type explanation

There are seven types of arguments that might be passed to building block.


  • Number - simple type. Value passed as this type will be converted to Number.


  • String - Value passed as this type will be converted to String. Simple input field in inspector or Combobox component if options provided.
  • Boolean - only true or false value.
  • Array - value passed as this argument will be converted to Array.

  • Event Data - allows passing the result of another wired Value building block. To get value method rule.getDataDimensionVal() is used (see below). Useful If you want to compare event data with static value, or change it somehow.
    ○ Wire event data block to the right connector

    ○ Choose wired event data in dropdown in building block inspector.


  • Session Data - allows to send session data to building block code. Shows all available event data in inspector. Session data must be defined first.


  • Profile Attribute - allows to send session data to building block code. Shows all available event data in inspector. Profile attrbute must be defined first.


Rule object

Each building block has a link to the event object - “rule” - in which building block is being executed. It provides several usefull methods.


  • rule.trigger() - triggers current event. Used in building block of type Trigger. On the screenshot - the simple example of using method. This building block triggers the event in X seconds after page load. It takes number of seconds as argument, and when the timer expires the rule.trigger() will be called. bRef is used to pass reference to rule object ааinside anonymous function.
  • rule.getDataDimensionVal(<EventData object>) - is used in Conditions and Values to get value of the Event Data. It takes the Event Data as an argument and returns its value. Event data - argument type, the result of another wired building block of type Value.
    In example below there is a simple condition. There are two arguments: “Value name” - args.dd (Event data, need to be wired to any building block of type Value), “Should be equal to” - args.to (any static value set in inspector). First it gets the value of args.dd object, then compares it to the static value and returns the result.
  • rule.core.jQ - link to the jQuery library. With it you can access jQuery object currently available on the site, and use it as you want. For instance this is trigger building block code, it takes element selector string, event type string and uses jQuery to add event listener.
  • rule.core.cookie(name, [value, [options]]) - used to set and get cookies. First argument - name of the cookie to set or get. Second argument - cookie value to set, Third argument - options object. If second arguments is omitted the method returns value of cookie “name”. Otherwise it will set cookie value and name.

  • rule.core.createDataDimension(id, value) - creates new Event Data. Takes two arguments:
    ○ ID - used to access event data from other places: another building blocks with rule.getDataDimensionVal(ID) or adapters such as Targeted popup or On-site personalization with dd(id) method
    ○ Value - value of newly created event data.
    Can be used to share complex data (like objects) between building block. Usually it is used in Triggers, since they can’t be wired to any Event Data. In common case it used to keep jquery event object (e.i element which was clicked):

  • closureLiveEvent - id of the predefined event data. This Event data stores complete object of the event which happened in the In-page interaction building block (see example above). Can be received with rule.getDataDimensionVal(“closureLiveEvent”)

closureLiveTarget - id of the predefined event data. This Event data stores target of the event - element which has registered the event – either. event.target, event.srcElement or event.originalTarget of the event which happened in the in-page interaction building block (see example above). Can be recieved with rule.getDataDimensionVal(“closureLiveTarget”)


To find out if a building block is used in any events, go to the tab “building blocks” and click on the intended building block.


If it is used by any event it will be shown as above image (see Arrow). Click on the link and a list of the events will appear.



APSIS DataLayer is used to track your e-commerce data. In order to use this building block, a data layer has to be created on the site such as a JSON object, meta tags, hidden tags or any other data layer of your choice. The data layer has to be structured in a certain way.  At the bottom of this article, a guide is provided of how to create the data layer.


Two building blocks are used to cover e-commerce data.

  1. Order - is covering all data around the order in terms of order ID, price, currency, tax, Etc.
  2. Products – is covering product category, product name, SKU number, number of units, unit price Etc.

Drag the building blocks to the “Event data” area and select the relevant categories.


If the data layer has been implemented on the site each of above building blocks will automatically pick up the data. Connect each value with the relevant plugin such as Google analytics plugin or Sitecatalyst plugin.


DataLayer is to be structured as follow: 

(note: below example shows 2 products.)


APSISDataLayer = {
                "order":{
                                "id":"XXXXX",
                                "country":"XX",
                                "city":"XXXXXX",
                                "state":"XXXXXX",
                                "currency":"XXX",
                                "tax":"XXXX",
                                "total":"XXXX"
                },
                "product":[
                {
                                "sku":"XXXX",
                                "name":"XXXXXXXXXX",
                                "category":"XXX",
                                "unit_price":"XXXXXX",
                                "units":"X"
                },
                {
                                "sku":"XXX",
                                "name":"XXXXXX",
                                "category":"XXX",
                                "unit_price":XXXXX,
                                "units":X
                }
                ]

};


  


The data layer object on the website has to include all categories even if it is not applicable to you. Fill the categories that is not applicable to your data with any value, such as N/A, Null, Undefined or any other value of your choice.