Basic implementation of YouLead system on website consists of following steps:
- Tracking code installation
- Connecting contact forms with the use of:
- Product views tracking
- External links tracking
- Tracking any-event on the website
- Personalized elements on the website
Tracking code installation
Tracking code is a short JavaScript code, that should be placed on the website which will be connected to YouLead. The code should be placed precisely before </body> tag of the website. In the code, one should replace <clientId> with a unique customer ID obtained from the YouLead team.
<script type="text/javascript">
var youleadId = 'clientId';
var youleadDC = true;
(function() {
var yl = document.createElement('script');
yl.type = 'text/javascript';
yl.async = true;
yl.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'm-' + youleadId + '.youlead.pl/m.js?ts=' + (new Date()).getTime();
document.getElementsByTagName('body')[0].appendChild(yl);
})();
</script>You can also find the tracking code in the Settings/Integration section of the YouLead application.
Connecting contact forms
Contact forms can be integrated with YouLead in two ways:
- With the use of the JavaScript Api
- With the use of the server API
The difference between the two approaches is fundamental. In the case of the JavaScript API, the data is sent directly from the web browser to YouLead without the participation of the server on which the website is hosted. In turn, the server API allows you to transfer data to YouLead from the level of the web server. The first method is faster to implement, but can be more unreliable because it depends on the specifics of a particular website (e.g. whether the page reloads after completing the form or not). The second way is more complex to implement because each call requires authentication but is more reliable.
Integration of all forms in the website should be performed as follows.
Connecting forms with the use JavaScript API
In order to connect the contact forms available on the website to the YouLead system, perform the following operations:
a) To each field in the form (input), which value is to be saved in YouLead, one should add the css class with the name beginning with the prefix yl-. The value after the prefix will be used as the identifier of the form field sent to YouLead and will be displayed, for example, in the history of forms filled out by Contact. If the ID of the transferred field coincides with the alias of one of the attributes defined in YouLead – when saving the form, the value of this attribute will also be updated in the Contact who filled in the form. The situation is similar when it comes to consents, if such are defined in YouLead. Marking any of the fields in the form with the css class, which after the yl- prefix contains a string of characters corresponding to the alias of one of the consents in YouLead, may cause the change of the value of this consent in the Contact after he completes the form. The expected values of the consent fields are true or false.
The example
In the form, one of the fields is defined as follows:
<input type="text" id="hobby" class="yl-hobby userdefinedclass1 userdefinedclass2" value="describe your hobby" />The Contact fills out the form with the value “running” in the above field. After saving the form in the Contact card, there will be information about the completed form with the field: hobby: running. If among the attributes defined in YouLead there is one whose alias is hobby, then the value of this attribute will also be set to running in the Contact who filled the form (overwriting the previous value of this attribute).
There are predefined attributes in the system, aliases of which can be used for standard form fields:
- e-mail address: yl-email
- first name: yl-name
- last name: yl-lastName
- phone number: yl-phone
- city: yl-city
If the form contains other fields (for which there are no matching attributes in YouLead), one should create the css class names for these fields in any way that allows to distinguish them later, e.g .:
- ‘Body of the message’ field may be of the css yl-message class
- ‘Title’ field may be css yl-title class
As shown above, you can also pass the values of hidden fields to YouLead (similarly as in the above examples, give them the appropriate css class).
b) After the form has been validated, the Monitor.TrackForm function, which is available in the YouLead JavaScript API should be called. The function is available on the website after installing the YouLead monitoring code. Calling of this function sends data from the form to the YouLead system.
The example of the call:
Monitor.TrackForm('contactForm', postForm);A detailed description of the function and its parameters can be found in the API specification.
Please note the following:
1) calling the Monitor.TrackForm function should take place after the correct form validation
2) if sending the form to the server (submitting) causes the page to be reloaded, you should first call the JavaScript API that sends data to YouLead, and then the data transfer to the server (page reloading) should be performed only in the callback function which is passed to Monitor.TrackForm as a parameter – details in the API specification.
3) SMS status and E-mail status can be set in the Contact in several ways when filling out the form (the order of the described methods is important, if there is only one, the next ones are not taken into account):
- by explicit transfer of their values when calling Monitor.TrackForm
- if the above did not take place, then statuses may be set automatically according to the value of consents provided in the form (according to the rules contained in the description of the consent module)
- if the above did not take place, then it should be assumed that the default status values were provided when saving the form, as described in the JavaScript API
Connecting forms with the use server API
In order to connect the contact forms available on the website to the YouLead system, the method / Command / Contact / FillForm should be called from the Server Api methods described in the API specification.
The minimum data set that must be passed to the system is the ylid and the formData parameter. The ylid parameter should be read from the ylid cookie browser. The formData parameter should take the form of JSON containing a set of information about the submitted form fields. The field identifiers used will be displayed in the history of the forms filled out by the Contact. If the field identifier coincides with the alias of any of the attributes defined in YouLead – additionally, the value of this field will be entered into the attribute for the Contact when filling out the form.
The example
For the registration form on the website, the formData parameter may assume the following value:
"formData" : {
'email': 'john@doe.com',
'name': 'John',
'lastName': 'Doe',
'phone': '500111222',
'city': 'Warsaw',
'consent_processing': '1',
'consent_marketing': '1'}There are several predefined attributes in the system, which aliases can be used for standard forms, e.g .:
- Email address: email
- Name: name
- Surname: lastName
- Phone number: phone
- city: city
Despite the fact that other parameters of the FillForm method are not mandatory, it is recommended to pass them by:
- pageUrl (website url, where the form was completed)
- sessionId (ylssid cookie content)
- utm (ylutm cookie content)
- formId ((html form id of the completed form)
After the correct calling of the / Command / Contact / FillForm method, the new form filling is registered in the system. If the email address provided in the call already exists in the system, the form is added to the contact with this email address.
Remember, after the calling of / Command / Contact / FillForm method, print in the page code the string returned in the returnCode parameter – details in the method description in the API specification file.
You should also pay attention to the fact that calling the / Command / Contact / FillForm method should take place after the correct validation of the form.
Note: if the website uses the so-called ‘double-opt-in’ model, where the activation e-mail is sent by the website engine and not by YouLead – it is necessary to provide information about clicks on activation e-mails to YouLead. This can be done e.g. by calling the / Command / Contact / UpsertsByEmail method from the Server Api method described in the API specification with the statusEmail parameter set to 3 (Active). Sample value of contacts in calling this method:
"contacts":[
{
"requestId":123,
"emailKey":"john@doe.com",
"statusEmail":3
}
]Product views tracking
When describing product views tracking, two elements should be taken into consideration:
a. Preparation and transferring of url to product feed (detailed description in “YouLead – product feed specification”)
In all places of the website where products are viewed, you should use JavaScript API product function – passing the product / products identifier corresponding to the identifiers contained in the given product feed, which takes place during the calling. If several feeds are imported to YouLead in which product identifiers may be repeated (e.g. several feeds in different languages but with the same products) – add @feed after the product identifiers, where feed is the product feed identifier, where the currently viewed product is located.
Przykłady
ylData.push({ 'product': { 'products': ['a6d08b92-42ca-4457-9633-829e8371f76b@PL', 'a6d08b92-42ca-4457-9633-829e8371f76b@EN'] } });ylData.push({ 'product': { 'products': ['a6d08b92-42ca-4457-9633-829e8371f76b'] } });External links tracking
In order to send information to the YouLead system about the fact that the user clicks on an external link on a website (i.e. directs to a page where the YouLead tracking code is not embedded, e.g. social media websites, portals), you should add <a> element css yl-link class to the html
The example:
<a href="www.abcdefg.com" target="_blank" class="some_css_class yl-link">link zewnętrzny</a>Similarly, you can also track clicks on links to PDF, DOC, JPG files.
Clicking on external links can be used in YouLead to run previously defined rules and scenarios.
Tracking any-event in the website
In order to transfer to YouLead system information about an event on the website, a javascript API event method should be called. Thanks to the transfer of information about the event to the system, it is possible to define rules and scenarios in YouLead, which are launched after the event occurs.
Examples of events, which may be processed by YouLead:
- Slider movement on service subpage
- Phone number uncovering
- Popup display
- Customer’s journey through consequent steps of creator/configurator
Personalized elements on website
Thanks to YouLead we are able to display on the website personalized static elements e.g. banners, sliders, widgets. Adding such an element on a website is as simple as placing the appropriate <div> tag in the HTML code of the page in the place where the element should appear. After loading the website, the added div tag will be converted by YouLead scripts into an element personalized for a specific user.
<div> tag has to fulfil following requirements:
- div’s id must be correlated with dynamic view alias, defined in YouLead system
- div should contain css class with ‘yldynamiccontent’ value
- The width, height, and placement of the div tag depend on the purpose and function of the personalized item.
Note!:
Implementing YouLead means integrating it with a specific website structure and in some cases – a product feed. Changes to these structures without agreeing with YouLead may cause the defined mechanisms (tracking on websites, saved forms, popups, etc.) to cease to function properly. Therefore, YouLead should be informed about changes in the structure of the website or feed, in particular about:
- any changes to the forms on the website (including html of id forms)
- changes in the structure of the website especially where the content generated by YouLead is embedded (e.g. recommendation frames)
- changes in website URLs (e.g. rules and scenarios may depend on them)
- changes in the structure of the product feed (e.g. new columns in the csv file or changes in the xml file). It should also be taken into account that YouLead uses information about products (names, prices, photos) that were imported during the last import of the product feed. If the customer’s product database has changed after the last feed import, YouLead will use outdated product data for communication.
