Instruction manual of YouLead implementation in e-commerce service

Basic implementation of YouLead system in e-commerce service consists of following steps:

1. Tracking code installation
2. Registration – account set-up process
3. Newsletter sign-up
4. Logging into e-shop process
5. Product views tracking
6. Cart tracking
7. Purchase tracking
8. Tracking any-event on the website
9. Personalized elements on the website

There are two types of APIs described below:

• Javascript API – functions called directly in browser through HTML code
• Server-based API – functions called through dedicated server (requires authentication)

User account operations, i.e. registration and logging in require server-based API methods.

Mandatory parameter for server-based API calls is API Secret Key, which is shared to customer along with this  document.

Tracking code installation

Tracking code contains user ID, which is created by YouLead administrator. Javascript code, which is to be pasted into each service subsite, should be delivered along with this document.

The code should be placed precisely before </body> tag.

Registration – account set-up process

User registration (account set-up) on the website is served in YouLead by calling /Command/Contact/FillForm server-based API method.

Minimum data that has to be sent to the system is ylid and formData parameter. Ylid may be found in browser’s ylid cookie. 

Example:

For registration form containing following fields:

• e-mail address
• first name
• last name
• phone number
• city
• ToS acceptance
• processing of personal data consent
• electronic communication consent

formData parameter may get following values:

“formData” : {‘e-mail’: ‘jan@kowalski.pl’, ‘first_name’: ‘Jan’, ‘last_name’: ‘Kowalski’, ‘phone’: ‘500111222’, ‘city’: ‘Warszawa’, ‘ToS’: ‘1’, ‘data_proc_cons’: ‘1’, ‘elec_comm_cons’: ‘1’}

One can insert his own parameter values to formData. Especially it is worth to add userId parameter – an internal user identificator set in e-shop database.

Also, adding following parameters to formData should be considered:

• pageUrl (website url)
• sessionId (ylssid cookie content)
• utm (ylutm cookie content)
• formId (html form id)

After successful call of /Command/Contact/FillForm method, new contact is created in the system – we assume uniqueness of e-mail address.

Please mind that after /Command/Contact/FillForm call, you should print into website code string returned in returnCode parameter – see method description of API specification file.

Please consider also the fact that calling /Command/Contact/FillForm method should take place after successful form validation and successful user creation in e-shop database (again, we assume e-mail uniqueness).

Understanding that during account creation in e-shop this e-shop’s system sends user and e-mail containing activation link, process of account activation in the service may be defined as follows:

• Step 1: User registration in e-shop website and calling YL /Command/Contact/FillForm. Depending if the user checks marketing communication consent or not, we have two scenarios: 
  • If the consent is checked – Status parameter value should be 2 (Pending activation /Do aktywacji)
  • If the consent is not checked – Status parameter value should be 1 (No consent /Brak zgody)
• Step 2: After clicking activation link in activation e-mail, e-shop system calls YL method /Command/Contact/CustomEvent with parameter customEventName = „Activation”. In the YL system status is changed to Active afterwards and account is marked (Tag) as active Foregoing logic should be implemented  in specific rule of “Custom events“:
• This solution is a „double opt-in” method. A simpler single opt-in scenario is also available. It is launched when in the first step we call /Command/Contact/FillForm method with parameter Status = 3. As a consequence, there is no need to call Step 2 method afterwards anymore.

Newsletter sign-up

Newsletter sign-up is fulfilled in a similar way to user registration but with /Command/Contact/FillForm method.

We recommend double opt-in method, i.e.

1. First we call /Command/Contact/FillForm with parameter Status = 2 (Pending activation / Do aktywacji). YL System receives a contact with „Peindig activation” status and activation e-mail with activation link is automatically sent (an adequate rule in YL System for “Form filled” event should be defined).
2. If user clicks on activation link, Status in system is changed to Active.

Logging into e-shop process

After user successfully logs in, method /Command/Contact/Switch should be called. Alike case of registering method, it is important to print the code returned in returnCode parameter.

Product views tracking

Describing product views tracking, two elements should be taken into consideration:

1. Preparation and transferring of url to product feed (detailed description in “YouLead – product feed specification”)
2. In every place of your service where the products are viewed, you should use product function from javascript API, delivering in the call products’ IDs which respond to IDs placed in product feed.

Example:

ylData = window.ylData = window.ylData || []; ylData.push({ ‘product’: { ‘products’: [‘productId’] } });

Cart tracking

After each cart content change triggered by user, proper function should be called to push whole cart content to the system.

Javascript API function called cart is used. For detailed description of this method, see API specification file.

Purchase tracking

Purchase finalization is delivered to the system by dedicated purchase javascript API call. More details about this method and parameters may be found in API specification.

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. For details see YouLead API specification.

Examples of events, which may be processed by YouLead:

1. Slider movement on service subpage
2. Phone number uncovering
3. Popup display
4. Customer’s journey through consequent steps of creator/configurator

Personalized elements on the website

Thanks to YouLead we are able to display on the website personalized static elements e.g. banners/sliders. Adding of such an element is as simple as adding in HTML code proper <div> tag wherever we want the element to appear. During website rendering div will be exchanged with the content personalized for a given 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
• width, height and placing depend on the role and function of the element