Mailocator Documentation

Here you can find all information about basic settings and higly customized popups / overlays.

You can create free Mailnatives account with Mailocator unlimited trial at user.mailnatives.com

How to start?

Connect Mailocator with your pages

Connection is very easy, only what you have to do is get your unique snippet and place it to your pages.
Get your own snippet at: Mailocator > Campaign > Get snippet

Direct placement

Vložte javascriptový snippet Mailocatoru kamkoliv do strábky, nejlépe nad koncový tag BODY, tzn. nad HTML značku </body>

Placing using GTM (Google Tag Manager)

Otevřete Google Tag Manager, klikněte na tlačítko "Přidat novou značku" v bloku "Nová značka" a značku pojmenujte (v levém horním rohu).
V prvním kroku "Konfigurace značky" klikněte na "Vyberte typ..." a z nabídky vpravo vyberte "Vlastní HTML/Vlastní značka HTML".
Do textového pole vložte javascriptový snippet Mailocatoru.
V druhém kroku "Spouštění" klikněte na "Zvolte pravidlo..." a z nabídky vyberte "All pages".
Změny uložte kliknutím na modré tlačítko "Uložit".
Po uložení změny publikujte na váš web kliknutím na červené tlačítko "Publikovat".

Snippet example:

<script>
(function(e,a,d,b,c){a.mlctr=
{p:"https://mailocator.com",cpg:"XXXXXXXXXXXXXXXX"};
b=a.createElement(d);c=a.getElementsByTagName(d)[0];
b.async=1;b.src=a.mlctr.p+"/_/s/"+a.mlctr.cpg+"/ml.js";
c.parentNode.insertBefore(b,c)})(window,document,"script");
</script>

Způsoby předání nebo doručení sebraných dat

Emailingový nástroj

Nejčastější a nejpohodlněnší cestou je předáná dat přímo do nástroje pro hromadný mailing, jako je Mailchimp, Mailkit, Maileon, AWeber, ActiveCampaign a další.

K propojení s emailongovým nástrojem je vyžadován API klíč, token nebo jiný způsob autorizace, současně může byt vyřadován výbě složky s kontakty apod.

Webhook

Prostřednictvím webhooku je možné předat data libovolnému nástroji prostřednictvím HTTP metod GET/POST/PUT ve a to buď jako parametry, pole, JSON nebo XML.

Pro podrobné informace k vytvoření webhooku najdete zde

Přesměrování na URL

Po potvrzení formuláře může být uživatel přesměrován na libovolnou adresu s GET parametry.
Parametry mohou být zakódvané algoritmem Base64.

Mailocator SystemMail

Pro účely testování nebo pro menší objemy sebraných kontaktů lze využít integrovaný SysteMail a sebrané kontakty jsou doručeny na vaši e-mailovou adresu.

SystemMail podporuje Double-opt-in, který vyhovuje pravidlům GDPR.

Messages

Thank you

Po úspěšném odeslání kontaktu a dat je element s třídou mlctr-message-success nahrazen děkovnou hláškou.

			                                   
<div class="mlctr-message-success">
   <!-- thank you message will be here -->
</div>

Contact already exists / Duplicate

Pokud je zadaný kontakt již zapsaný v databázi připojeného e-mailového nástroje, iformace může být vypsána do elementu s třídou mlctr-message-error.

			                                   
<div class="mlctr-message-error">
   <!-- duplicate contact message will be here -->
</div>

System Error

Informace o chybě v komunikaci s nástrojem třetí strany může být vypsána do elementu s třídou mlctr-message-error.

			                                   
<div class="mlctr-message-error">
   <!-- duplicate contact message will be here -->
</div>

Multi-step, vícekrokové zobrazení

Pokud používáte dotazníky nebo strukturované sbírání dat, další obsahy (kroky) přepisují obsah elementu s třídou mlctr-next-step.

Počet kroků není početm omezen.
Přechod mezi kroky je řízen pomocí Akcí - mailocator.actions.do().

			                                   
<div class="mlctr-next-step">
   <!-- duplicate contact message will be here -->
</div>

Form fileds and inputs

Form

Všechny inputy, které budou Mailcatorem zpracovány, musí být umístěny ve formuláři s ID MailocatorForm.
All HTML5 input types are fully supported.
Form processing is provided by onsubmit event or another custom event on button, imeage etc. As events are considered Mailocator Actions, see below.

			                                   
<form 
   id="MailocatorForm" 
   onsubmit="return mailocator.action.do('subscribe')" >
...
</form>

Email

Input pro zadání e-mailové adresy musí mít vždy atribut name nastavený na email - name="email". Může být použit type email nebo text.

			                                   
<input type="email" name="email"  value="" placeholder="" />

Custom fields

If your ESP supports Custom fileds, you can enrich your records by information you want. Typically you can deliver information about objects of user's interests, nationality, information from datalayer, cookies and more. You can also use custom fields for inputs in your questionnaire and/or from multi-step-popups.

If you want to deliver data from popup to custom fields, you must use prefix opt_ for such input.

			                                   
<input type="hidden" name="opt_eshopCategory" value="Fruits">

System Fields

System fields are pre-defined fields in your ESP's recipient list, it can vary due to specific ESP. Typically it can be fields for storing vocations, genders, names, addresses, locations and so on.

If you want to deliver data from popup to this fields, you must use prefix sys_ for such input.

			                                   
<input type="radio" name="sys_gender" value="man">
<input type="radio" name="sys_gender" value="woman">

Promocodes, Gift coupons

Mailocator can automatically append promocode to all successfuly processed subscribtions.

You can assign promocode stock for every or selected trigger, so for example you can send promocde only in Welcome process.

Your codes (generated from eshop or marketing engine) can be imported in CSV into Mailocator Promocode Manager ( see Features&Settings > Promocodes ).

Two types of codes are supported:

Daily basis - one code is dedicated for one day, all subscribes will receive the same code
Unique basis - each code is unique, every user will receive his own code

Delivery to email service

By default, if promocodes are on and available, code will be delivered as a custom field - promocode.
No hidden input or so is needed.

You can also define field name, jsut add hidden input with desired custom filed as name.
As a value just eneter tag {[PROMO_CODE]} which will be replaced with real code.

			  

	                                 
<input type="hidden" name="opt_FiledName" value="{[PROMO_CODE]}">

Display code and code message in popup

When successfuly subscribed, you can also display his code and code message (ie. "Free delivery") in thak you page.

Use replacement tags {{PROMO_CODE}} and/or {{PROMO_CODE_TEXT}}.

			  

	                                 
Congratulations, you have {{PROMO_CODE_TEXT}} !
Use following code: {{PPROMO_CODE}}

Customized popup coding

Základní struktura okna

Základní struktura kódu je zložena na následujícíh prvcích:

překryv pozadí .mlctr-popup-background
kontejner pro zobrazení obsahu okna .mlctr-popup
všechny vstupy musí být umístěné v kontejneru form s událostí mailocator.action.do('subscribe')
kontejner pro zobrazení poděkování nebo doknčení procesu .mlctr-message-success
kontejner pro zobrazení chyb a oznámení .mlctr-message-error
zavírací křížek nebo tlačítko s událostí mailocator.action.do('close')

Basic popup sample:

			                                   
<!-- transparent fullscreen background -->
<div class="mlctr-popup-background">

<!-- master popup div container -->
<main class="mlctr-popup">

<!-- following onsubmit event is required -->
<form onsubmit="return mailocator.action.do('subscribe')">
  <h1>This is the popup... </h1>
  <!-- following div will be overwritten with success message -->
  <div class="mlctr-message-success">
     <!-- overwrite following content on success -->

     <div class="mlctr-message-error">
        <!-- display error messages here -->
     </div>
   
     <label>Your e-mail address</label>  
     <!-- input with attribute name="email" is required -->
     <input type="text" name="email" />
     <input type="submit" value="Subscribe" />

     <!-- following event closes popup by users action -->
     <input type="button" value="Close" 
         onclick="mailocator.action.do('close')" />
  </div>
</form>

</main><!--/end of my-popup-container -->
</div><!--/end of my-popup-background-layer -->

Základní požadavky na CSS

Nastavení průhlednosti pozadí a zafixování zobrazení

Principem je překytí obrazovky po celé výšce i šířce elementem s poloprůhledným pozadí.

			                                   
.mlctr-popup-background {
    z-index: 999999; 
    position: fixed; 
    width: 100%; height: 100%; 
    top: 0px; left: 0px; 
    background-color: rgba(0, 147, 248, 0.207843);
}

Nastavení pozice okna

Okno je umístěno na střed překryvu obrazovky.

Pro správné zobrazení na mobilních zařízeních je třeba přidat potřebné media-query css.

			                                   
.mlctr-popup {
    position: relative;
    height: auto;
    width: 500px; max-width: 100%;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
}

Custom Javascript

Jakýkoliv doplňující kód Javascriptu lze připojit k jakékoliv kampani, tedy všem oknům v rámci jedné kamapně.
Připojení skriptu je možné výhradně přes rozhraní aplikace Mailocator - Popupy > Javascript.

Uživatelský kód je prováděn před samotnou inicializací objektu mailocator, pokud tedy obsahuje chybu, Mailocator se nespustí.

Nikdy nevkládejte javaskript do okna popupu, mohl by být označen prohlížečem jako XSS (cross site scripting) a nemusí být proveden.

Display pop-up by URL parameter

You can pass GET parameter "mailocator=" and display popup from URL by given value

https://www.example.com/?utm=abcd&mailocator=...

Display by design ID

URL Parameter: design id

Open Designer, choose your design, click to Properties and ger your design ID.

	        	
https://www.example.com/?mailocator=123

Display by trigger name

URL Parameter: trigger name

Trigger name	Description
reset	reset Mailocator session, remove all cookies
cookies	show all readable cookies
welcome	run welcome trigger
time	run time dalay trigger
scroll	run scroll trigger
mouse	run cursor trigger

	        	
https://www.example.com/?mailocator=welcome

Actions

Actions are used to handle Mailocator over javascript events used in your popups or designs.
You can use actions to display popup, close popup, subscribe form, validate form, display popup or design into given element and much more.

How can I use it?

Simple call action you need by following statement:
mailocator.action.do( 'action_name' )

You can also run more actions...
mailocator.action.do( 'action1|action2|next_action' )

And you can give some parameter to action...
mailocator.action.do( 'action:parameter' )

Where to use it?

In most cases actions are fired from javascript events like onclick, onsubmit etc.

Subscribe new email:

	        	
<form id="MailocatorForm" 
onsubmit="mailocator.action.do( 'submit' ); return false">
....
</form>

Close window if user click on the image

<img src="h/img/close-button.png" 
 onclick="mailocator.action.do( 'close' )" />

Close window

Parameter: none or number of seconds

Close pop-up window immediately.
Action: close

Close popup with delay

Close pop-up window after given number of seconds
Action: close:5 - close window after 5 seconds

	        	
mailocator.action.do(‘close’)

mailocator.action.do(‘close:5’)

Subscribe

Parameter: none or number

If sigle popup is used, validate form and save data or return error message.
Action: subscribe

Force to subscribe, useful on static multiple forms/designs.
Action: subscribe:1

Collect data but disable saving to mailist and delivery to ESP.
Action: subscribe:0

mailocator.action.do(‘subscribe’)

mailocator.action.do(‘subscribe:1’)

mailocator.action.do(‘subscribe:0’)

Get Mailocator version

Obtain Mailocator snippet verison if successfully implemented.
Version number is shown in browser alert.
Action: version

mailocator.action.do(‘version’)

Reset users session

Reset popup and design settings wile debugging or testing popup behavior.
Action: reset

mailocator.action.do(‘reset’)

Place poup HTML code into page element

Required parameters: number of design ID and html element id

Place design given in by ID to HTML element id given as second parameter.
You can place your design to specific place on your page as static element.
Action: placeToElementId

Optional parameter: new-user-only

Display design ID 1234 to DIV with id 'my_element'

<div id="my_element">
  Design will be placed here when page is loaded...
</div>

<script>
window.onload = function(){
    mailocator.action.do(‘placeToElementId:1234, my_element’);
}
</script>

Display content only for new (not subscribed) users

mailocator.action.do(‘placeToElementId:1234, my_element, new-user-only’)

Add event to Google Analytics

Required parameters: name of your event

Promote evenet to Google Analytics account assigned to your pages.
Your GA code must be placed in your page first.
Action: GA

mailocator.action.do(‘ga:user-click’)

Display popup with given scenario

Required parameters: scenario name

Force to display given popup or design by scenario type.
Action: display

Allowed scenarion types: welcome, time, repeat, mouse, scroll, repeatmouse, repeatscroll, reminder, cookies

mailocator.action.do(‘display:welcome’)

Display popup with given design ID

Required parameters: number of design

Force to display given design by id.
To obtain ID click to property button in designer or code editor.
Action: displayID

mailocator.action.do(‘displayID:1234’)

Switch Mailocator off

Disable all Mailocator processes until Enable action is called.
Action: disable

mailocator.action.do(‘disable’)

Switch Mailocator on (if disabled)

Enable all Mailocator processes if they were disabled before.
Action: enable

mailocator.action.do(‘enable’)

Extensions

Extensions of Mailocator default functionality.

Mailocator Extensions must be switched on, see your Campaign settings

Merge inputs into one value

Sometimes you need to merge some differrent values into one.
It can be easier to use one complex date value instead two (month and year) in you ESP mailings.

Use class name with keyword mlctr-ext-merge and define the data-merge attribute containing inputs to merge splitted by `|`. When popup is submited, value opt_date (or date) is delivered to your ESP custom filed.

			                                   
<select name="year">
  <option value="1999">1999</option>
  <option value="2019">2019</option>
</select>

<select name="mon">
  <option value="jan">jan</option>
  <option value="feb">feb</option>
</select>

<input type="hidden" name="opt_date" 
   data-merge="year|mon" 
   class="mlctr-ext-merge" 
   value="0"/>

Popup with time countdown

You can easily put well customized countdown timer into your own popup without any scripts or external tools.

Define your countown simply by following attributes of DIV (or any block type) element with class name mlctr-ext-countdown and data-end and data-end-message attribute.
At first simply create countdown parent element and place DIV element on proper place at your popup source code, add class called mlctr-ext-countdown.
- Set countown date and time by attrribute data-end in following format YYYYMMDDHHMMSS
- Set message to display when time has been reached into attribute data-end-message.
- Into element with class name mlctr-ext-countdown insert tags where time till the end will be displayed.
- Place SPANs (or any inline/block types) with classnames day, hour, min and sec customize your design by timer class names.

			                                   
<div class="mlctr-ext-countdown" 
   data-end="20170630150000" 
   data-end-message="Oops, campaign has been finished!">
   <span class="day"></span> days,
   <span class="hour"></span> hours,
   <span class="min"></span> minutes
   <span class="sec"></span> seconds left
</div>

Display direct link to visitors email vendor service

You can easily display link to email vendor to increase conversion rate, using this feature in following cases:
- Thank you message or Thank you popup
- Reminder (strictly recommended)

At first define vendors list in your popup code.
You can place so much vendors as you want, every following input must have increased serial number of it's name - name="mlctr-email-vendor-1".

Parameter	Explanation
data-vendor-name	name of email vendor, any string is accepted
data-vendor-domain	domain name behind @ in email address, ie. gmail.com or yahoo.com
data-vendor-url	target url you want to redirect visitor to check and confirm email message

Result code will be displayed only if user's email vendor is on your previously defined list of supported vendors. If vendor is found, %url% and %name% is replaced with proper content given in vendor list.

Vendors definitions:

			                                   
<input type="hidden" 
   name="mlctr-email-vendor-1" 
   data-vendor-name="Yahoo" 
   data-vendor-domain="yahoo.com" 
   data-vendor-url="https://email.yahoo.com" />
<input type="hidden" name="mlctr-email-vendor-2" data-vendor-name="GMail" data-vendor-domain="gmail.com" data-vendor-url="https://gmail.com" />
<!-- place more mlctr-email-vendor-X hidden inputs here ... -->

Link to vedor:

        
<span class="mlctr-email-vendor-link" style="visibility:hidden">
  <a href="%url%" target="_blank">Go to %name%</a>
</span>

Confirmation checkbox - confirm agreement

You can easily deploy verification ceckbox to force user to confirm processing popup form.

Simpy place whenever into your popup code input with the checkbx type and class name called mlctr-verification.

You can display optional message to user, if following DIV (or other inline/block element) is defined with classname mlctr-verification-alert.

If user try to submit form with unchecked checkbox, optional message class name is expanded to mlctr-verification-alert display. You can modify the classnames to create display/hide effect, highliting, emphasization or other visual effect.

Create checkbox:

			                                   
<input type="checkbox" name="mlctr-verification" />

Alert:

			                                   
<div class="mlctr-verification-alert">
    Please confirm your request before sumbit
</div>

Callback

Run callback function when Mailocator is loaded

You can run callback function when Mailocator is inited and all properties are loaded.
Simply place function named mlctrCallback to Popup > Javascript window.

			                                   
var mlctrCallback = function(){
alert( 'Mailocator version: ' + mailocator.version );
};

General Data Protection Regulation (GDPR)

Mailocator is GDPR compliant system.
We recommend to use GDPR feature in your campaings however it is not required now.

Changes after february 1st of 2018:

all personal data in Mailocator will be anonymized including data collected before
single op-in will be disabled in all connectors, double-opt-in will be reqired method
Mailocator will never processed personal data or any data which can be used to user identification
local Mailocator maillist will be deprecated

How to start?

Data prcessing and delivery

Messages

Form fileds and inputs

Promocodes, gift coupons

Customized popup coding

Trigger by URL

Actions

Extensions

Callback functions

ESP specifications

GDPR

Mailocator Documentation

How to start?

Connect Mailocator with your pages

Direct placement

Placing using GTM (Google Tag Manager)

Způsoby předání nebo doručení sebraných dat

Emailingový nástroj

Webhook

Přesměrování na URL

Mailocator SystemMail

Messages

Thank you

Contact already exists / Duplicate

System Error

Multi-step, vícekrokové zobrazení

Form fileds and inputs

Form

Email

Custom fields

System Fields

Promocodes, Gift coupons

Delivery to email service

Display code and code message in popup

Customized popup coding

Základní struktura okna

Základní požadavky na CSS

Nastavení průhlednosti pozadí a zafixování zobrazení

Nastavení pozice okna

Custom Javascript

Display pop-up by URL parameter

Display by design ID

Display by trigger name

Actions

How can I use it?

Where to use it?

Close window

Close popup with delay

Subscribe

Get Mailocator version

Reset users session

Place poup HTML code into page element

Add event to Google Analytics

Display popup with given scenario

Display popup with given design ID

Switch Mailocator off

Switch Mailocator on (if disabled)

Extensions

Merge inputs into one value

Popup with time countdown

Display direct link to visitors email vendor service

Confirmation checkbox - confirm agreement

Callback

Run callback function when Mailocator is loaded

General Data Protection Regulation (GDPR)

Changes after february 1st of 2018: