Edrone Custom Integration

2017.05.31

How it works

Edrone is a system for collecting and analyzing customer behaviour. Collected data and out-of-the-box engagement scenarios allow the system to increase customer retention.

Glossary

Site/Shop/Retailer/Company - e-commerce site that is integrated with edrone SaaS (e.g. online shoes shop).

Integration - process of setting up retailer’s site to work with edrone. This includes registering an account, installing module and/or making server side changes on retailer’s site, etc.

Custom Integration - integration that does not take advantage of available modules for e-commerce sites. It is typically required when the e-commerce platform does not offer sufficient extensibility mechanism (e.g. rendering custom JS scripts, access to data, etc.) or it is a custom-built store.

Module - package provided by edrone company. It allow easy integration between e-commerce platform and edrone system. We provide modules for most of popular e-commerce platforms e.g. Magento, Prestashop, IAI, Shoplo, Shoper, Woocommerce, Shopify, Sote, Opencart etc.

Tracker - individual account in the edrone system.

  • Uniquely identified by App Id
  • Managed by Agents
  • It represents a shop in edrone

App Id - unique identifier for a tracker. It is inserted in the retailer's JS tracking code and passed by customer browser (e.g. 53a97649ea0b3).

Onboarding - process of helping newly integrated shop owner to configure his account, design engagements, etc.

Mission Control - (https://control.edrone.me) administration panel for shop owners. It allows to manage Engagements, view reports, etc.

Customer - person who uses retailer services and has email address. Data generated by customers (visits, orders etc.) are collected and analyzed by edrone.

Agent - user that manages edrone Account. More than one agent can be associated with an account (i.e. Tracker).

Engagement - a process of encouraging somebody to return to the retailer site. It is typically a workflow consisting of multiple steps that has trigger conditions associated with them, e.g. RESTORE CUSTOMERS, RECOVER ABANDONED CARTS, etc.

Trace - data describing customer interaction on the e-commerce site. We trace the following types of interactions:

  • PRODUCT_VIEW - customer viewed a product
  • ADD_TO_CART - customer added a product to the cart
  • ORDER - customer made an order
  • OTHER - other interaction
  • SUBSCRIBE - customer subscribed to emails (using a pop-up)*
  • ORDER_CANCEL - for instance, order was unpaid

Coupon - a code that allows user to obtain a discount. It is generated by retailer and uploaded to edrone. Coupons are included in the message and redeemed at retailer’s site.

  • Static coupons - identical code is sent to all customers. The code is set in Mission Control.
  • Dynamic coupons - each customer receives unique code. Codes are generated by e-commerce platform and uploaded to edrone via Mission Control.

Drag’n’Drop editor - visual editor for creating HTML email templates based on dragging and dropping components (e.g. text blocks, placeholders, image elements)

HTML editor - visual editor for creating HTML code directly. Every email created in Drag’n’Drop editor can be edited in HTML editor. However, you cannot return to editing it in Drag’n’Drop editor after direct HTML modification.

Dynamic Placeholder - an element that can be added to email design. When email is sent to a specific Customer the placeholder is replaced with personalized image, text etc.

Spender - customer who made at least one order.

One-Time Spender - *spender8 who made exactly one order.

Repeat Spender - spender who made more than one order.

Inactive Customer - customer who has not visited the site for a specified period of time.

No Risk Inactive Customer - customer who has not visited the site [0, 7) days.

Low Risk Inactive Customer - customer who has not visited the site [7,30) days.

High Risk Inactive Customer - customer who has not visited the site for [30,∞) days

Spender Value - total value of orders made by a spender. Example: customer who made two orders 24$ and 36$ has a spender value of 60$

Low Spender Threshold - it is calculated so that the Low Spenders segment holds 80% of customers with the lowest total purchase value. Mathematically, it is the 80th percentile of spenders value. Separates Low Spenders from Medium Spenders.

Big Spender Threshold - it is calculated so that the Big Spenders segment holds 1% of customers with the highest total purchase value. Mathematically, it is the 99th percentile of spenders value. Separates Medium Spenders from Big Spenders.

Low Spender - spender whose value obtained by edrone algorithm is equal to or less than value of Low Spender Threshold. Typically Low Spenders group has many members.

Big Spender - spender whose value obtained by edrone algorithm is greater than Big Spender Threshold. Typically Big Spenders group has few members.

Medium Spender - spender whose value is between Low Spender and Medium Spender.

Frequent Spender - spender who is in top 25% who made the highest number of orders (order value is not considered here).

Trend Setter - customer who is active on Social Media.

Prospect - customer who has not made any order, yet (i.e. he is not a Spender).

Subscription Status - whether or not recipient wants to receive email

  • SUBSCRIBED
  • UNKNOWN - no information is available (e.g. it is not provided by e-commerce platform)
  • UNSUBSCRIBED

Double Opt-In - process of obtaining e-mail subscription consent. Upon entering email address recipient is sent an email containing unique subscription confirmation link. When the link is clicked the email address is marked as subscribed. This process can be implemented by the shop itself or by edrone using NEWSLETTER SUBSCRIPTION Engagement.

* Historical integrations may use OTHER for this interaction

Sending data to Edrone

E-commerce server generates JavaScript code which is returned to the end customer browser. In effect the end customer browser sends the data to Edrone servers.

Example JavaScript code:

<script type="text/javascript">
   (function (srcjs) {
       window._edrone = window._edrone || {};
       _edrone.app_id = '51a97611a3430';
       _edrone.version = '1.0.0';
       _edrone.platform_version = '';
       _edrone.platform = 'ebexo';
       _edrone.email = 'test@example.org';
       _edrone.phone = '';
       _edrone.first_name = 'John';
       _edrone.last_name = 'Smith';
       _edrone.product_skus = 'MAK03035';
       _edrone.product_ids = '3434';
       _edrone.product_titles = 'SANTI-DONNA';
       _edrone.product_images = 'http://x.z..com/media/s/x/cache/3/image/df/3/u/3u1a6597--1200q100.jpg';
       _edrone.order_id = '';
       _edrone.order_payment_value = '';
       _edrone.currency = '';
       _edrone.action_type = 'product_view';
       _edrone.country = 'Poland';
       _edrone.city = 'Krakow';

       var doc = document.createElement('script');
       doc.type = 'text/javascript';
       doc.async = true;
       doc.src = ('https:' == document.location.protocol ? 'https:' : 'http:') + srcjs;
       var s = document.getElementsByTagName('script')[0];
       s.parentNode.insertBefore(doc, s);
   })("//d3bo67muzbfgtl.cloudfront.net/edrone_2_0.js");
</script>


edrone_2_0.js - External Javascript library provided by edrone.
Url: https://d3bo67muzbfgtl.cloudfront.net/edrone_2_0.js It should be initialized once using the following script

<script type="text/javascript">
   (function (srcjs) {
       window._edrone = window._edrone || {};

       _edrone.app_id = 'YOUR APP_ID';

       var doc = document.createElement('script');
       doc.type = 'text/javascript';
       doc.async = true;
       doc.src = ('https:' == document.location.protocol ? 'https:' : 'http:') + srcjs;
       var s = document.getElementsByTagName('script')[0];
       s.parentNode.insertBefore(doc, s);
   })("//d3bo67muzbfgtl.cloudfront.net/edrone_2_0.js");
</script>


_edrone.init() - Function that is used to send data to edrone. It is automatically initialized after event "window.onload".

Example

<script>
$('#submit-button').on('click', function(){
    _edrone.customer_tags = 'From PopUp';
    _edrone.email = $('#input-email').val();
    _edrone.first_name = $('#input-name').val();
    _edrone.subscriber_status = '1';
    _edrone.action_type = 'subscribe';
    _edrone.init();
});
</script>


Fields with multiple values Certain event types may require multiple values in the trace field. For example when an “order” event occurs the customer might have purchased multiple items.

In order to specify multiple values in a field separate them by pipe character (“|”)

Example

_edrone.product_skus = 'MAK03035|FE01041';


The following fields allow multiple values:

  • product_ids
  • product_titles
  • product_images
  • product_skus
  • product_urls
  • product_category_ids
  • product_category_names
  • customer_tags
  • product_counts

A single product may belong to multiple categories (product_category_ids I product_category_names). In such case each category should be separated by “~” character.

Example

 _edrone.product_category_ids = '12~24~36';
 _edrone.product_category_names = 'Buty~Buty damskie~Szpilki';


Character encoding Any special characters (e.g. ", ‘,<,>,&,) should be encoded using url_encode function

Tags

Tags are used to associate additional information about a customer. This information may be later used in engagements.

Example


_edrone.customer_tags = 'gamer';


Before sending tags you must define them in edrone

Note: you can define maximum 64 Tags

Subscription

Customer agreement to receive emails is send in subscriber_status field. This information is send in every Trace and edrone updates internal database accordingly. Each customer must have one of the following states.

Value Description
SUBSCRIBED Customer is SUBSCRIBED and will receive emails.
UNSUBSCRIBED Customer is UNSUBSCRIBED and will not receive emails.
UNKNOWN Customer subscription status is not known.

Subscription pop-up - Use the “subscribe” action to send the information about subscription status.

Example

<script>
$('#submit-button').on('click', function(){
    _edrone.customer_tags = 'From PopUp';
    _edrone.email = $('#input-email').val();
    _edrone.first_name = $('#input-name').val();
    _edrone.subscriber_status = '1';
    _edrone.action_type = 'subscribe';
    _edrone.init();
});
</script>


  • $('#submit-button') - identifier of the subscription pop-up button
  • $('#input-email').val(); - value of the email field
  • $('#input-name').val(); - value of the first name field

Syncing subscription status

edrone offers a mechanism to notify the e-commerce platform that customer subscription status has been changed. E-commerce platform needs to provide a HTTPS endpoint that will be automatically called upon subscription status change.

Example https://www.a_shop.com/update_subscriber_status

The following fields are sent (POST) to e-commerce platform.

Parameter name Description
email Customer email address
subscriber_status
    Email subscription status:
  • 0 - unsubscribed
  • 1 - subscribed
  • empty - information not available
event_date UTC date when the customer subscription status was changed.
event_id Unique event identifier
app_id Unique shop identifier - available in Mission Control (Settings > Integration)
signature HMAC that can be used by ecommerce platform to verify that the request is authentic. It uses a secret (app_secret) that is available in Mission Control (Settings > Integration)

Example (PHP)
$hash=hash("sha256",$email.$subscribeStatus.$eventDate.$eventId.$secret.$appId, false);
$signature = base64_encode($hash);

Wishlist

The “WISHLIST” engagement allows to send e-mail to all customers awaiting certain event (e.g. customer receives notification that shoe size he is waiting for is now available). In order to use it the e-commerce platform needs to send two additional events.

topic_observe
Url: https://api.edrone.me/topic_observe

Sent when customer observes an event (e.g. shoe size availability)

Field Description
app_id See Trace API below
email See Trace API below
topic_id Topic identifier is used to match topic_observe event with topic_publish event.
topic_campaign_id Campaign identifier of the observed topic. It can be viewed in Mission Control.

Example https://api.edrone.me/topic_observe?app_id=bdag3h3563u&email=przykladowyemail@gmail.com&topic_id=dg623be63bbs&topic_campaign_id=0

topic_publish
Trigger notification for all the customers observing the topic. Url: https://api.edrone.me/topic_publish

Value Description
app_id See Trace API below
topic_id Topic identifier is used to match topic_observe event with topic_publish event.
product_ids See Trace API below
product_urls CSee Trace API below
product_skus See Trace API below
product_titles See Trace API below
product_images See Trace API below
product_category_ids See Trace API below
product_category_names See Trace API below

Appendix

Trace API

Parameter name Api Version Description
app_id 20150609 Application identifier. Uniquely identifies an e-commerce site. It is assigned by Edrone when new account is created. It must be set on the e-commerce site - typically by configuration screen.
c_id 20150609 Unique customer tracking identifier. Stored by customer browser. This field is automatically generated by edrone_2_0.js script.
version 20150609 Version of the module installed on the e-commerce site.
email 20150609 Customer email address
first_name 20150609 Customer first name
last_name 20150609 Customer last name
product_ids 20150609 Product identifiers for products that were viewed, added to cart or ordered. In case of Magento and Prestashop these are internal database product ids.
product_titles 20150609 Name of the product: viewed, added to cart or ordered by the customer.
product_images 20150609 Absolute urls to the images of the products viewed, added to cart or ordered by the customer.
order_id 20150609 Unique e-commerce site identifier of the order made by the customer.
action_type 20150609
    Type of action performed by customer:
  • product_view - individual product page
  • add_to_cart - added an item to the cart
  • order - customer has successfully completed and order
  • subscribe - subscription (typically pop-up)
  • order_cancel - customer order has been cancelled
  • other - none of the above
country 20150609 Customer country
city 20150609 Customer city
base_currency 20150619 Currency in which an e-commerce site operates. In case of e-commerce sites with multiple currencies this represents the main (global) currency.
order_currency 20150619 Currency in which the customer order has been made. It may be different from e-commerce site base currency.
base_payment_value 20150619 Total payment value of the order completed by the customer expressed in base_currency.
Mandatory field for Order events. Used a basis for all revenue calculations
order_payment_value 20150619 Total payment value of the order completed by the customer expressed in the order_currency. Used when e-commerce site allows purchasing products in various currencies.
phone 20150724 Customer phone number
coupon 20150724 Coupon used during order
platform_version 20150812 Version of the e-commerce platform (e.g. 1.9.2.1 for Magento)
product_skus 20150819 Product SKUs (stock keeping unit) for products that were viewed, added to cart or ordered.
platform 20151026 Name of the e-commerce platform (“customer”, “magento”,”prestashop”, “shoper”, “iai”,”shopify”,”shoplo”,”selly”,”shopify”,”woocommerce”,”bigcommerce”,”tictail”)
subscriber_status 20151113
(20160531)
    Email subscription status:
  • 0 - unsubscribed
  • 1 - subscribed
  • empty - information not available
utc_time 20151113 UTC server time when snippet was generated.
product_urls 20160104 Absolute urls of the products,
product_category_ids 20160307 Category identifiers for each product in the trace. Only one category per product is allowed. Multiple entries are separated by pipe character “|”.
product_category_names 20160307 Category names for each product in the trace. Only one category per product is allowed. Multiple entries are separated by pipe character “|”.
customer_tags 20160406 Tags to be associated with the customer. Multiple entries as separated by pipe character “|”
product_counts 20160831 Count of product. Multiple entries as separated by pipe character “|”
sender_type 20161201
    Indicates who is sending a trace
  • browser (default if absent)
  • server
shop_lang 20170127 Shop language version
shop_id 20170127 Identifier of the shop (used by Magento)
website_id 20170127 Shop website identifier (used by Magento)

Trace API - Mandatory fields for all action types

Parameter name Trace Action Type
Other Product View Add To Cart Order Subscribe Order
Cancel
app_id M M M M M M
version M M M M M M
action_type M M M M M M
platform_version M M M M M M
platform M M M M M M
sender_type M M M M M M

Trace API - Mandatory fields for specific action types

Parameter name Action Type
Other Product View Add To Cart Order Subscribe Order
Cancel
email A A A M M M
first_name A A A M A
last_name A A A A A
product_ids M M M
product_titles M M M
product_images M M M
order_id M M
country A A A M A
city A A A M A
base_currency M
order_currency M
base_payment_value M
order_payment_value M
phone A A A A A
coupon A
product_skus M* M* M*
subscriber_status M
product_urls M M M
product_category_ids A A A
product_category_names A A A
customer_tags A A A A A
utc_time A A A A A
product_counts A M
shop_lang A A A A A A
shop_id A A A A A A
website_id A A A A A A

* - if there are no product_ids
M - mandatory field
A - optional field

JavaScript examples

Other


<script type="text/javascript">
       _edrone.app_id = '51a97611a3430';
       _edrone.version = '1.0.0';
       _edrone.action_type = 'other';
       _edrone.platform_version = '1.1.26';
       _edrone.platform = 'prestashop';
</script>

Product view


<script type="text/javascript">
       _edrone.app_id = '51a97611a3430';
       _edrone.version = '1.0.0';
       _edrone.action_type = 'product_view';
       _edrone.platform_version = '1.1.26';
       _edrone.platform = 'prestashop';
       _edrone.product_skus = 'NL1975286';
       _edrone.product_ids = '12';
       _edrone.product_titles = 'Sorel Women's shoes Glacy';
       _edrone.product_images = 'http://demo-store.edrone.me/img/p/4/5/45-large_default.jpg';
       _edrone.product_urls = 'http://demo-store.edrone.me/index.php?id_product=12&controller=product';
       _edrone.product_category_ids = '2~3~4';
       _edrone.product_category_names = 'Główna~Shoes~Women's shoes';
</script>

Add to cart


<script type="text/javascript">
       _edrone.app_id = '51a97611a3430';
       _edrone.version = '1.0.0';
       _edrone.action_type = 'add_to_cart';
       _edrone.platform_version = '1.1.26';
       _edrone.platform = 'prestashop';
       _edrone.product_skus = 'NL1975286';
       _edrone.product_ids = '12';
       _edrone.product_titles = 'Sorel Womens shoes Glacy';
       _edrone.product_images = 'http://demo-store.edrone.me/img/p/4/5/45-large_default.jpg';
       _edrone.product_urls = 'http://demo-store.edrone.me/index.php?id_product=12&controller=product';
       _edrone.product_category_ids = '2~3~4';
       _edrone.product_category_names = 'Główna~Shoes~Womens shoes';
</script>

Order


<script type="text/javascript">
       _edrone.app_id = '51a97611a3430';
       _edrone.version = '1.0.0';
       _edrone.action_type = 'order';
       _edrone.platform_version = '1.1.26';
       _edrone.platform = 'prestashop';
       _edrone.email = 'jan.kowalski@edrone.me';
       _edrone.first_name = 'Jan';
       _edrone.last_name = 'Kowalski';
       _edrone.subscriber_status = '1';
       _edrone.product_skus = 'NL1975286|NL2075286';
       _edrone.product_ids = '12|13';
       _edrone.product_titles = 'Sorel Womens shoes Glacy|Sorel Womens shoes Glacy Explorer Shortie';
       _edrone.product_images = 'http://demo-store.edrone.me/img/p/4/5/45-large_default.jpg|http://demo-store.edrone.me/img/p/4/7/47.jpg';
       _edrone.product_urls = 'http://demo-store.edrone.me/index.php?id_product=12&controller=product|http://demo-store.edrone.me/index.php?id_product=13&controller=product';
       _edrone.product_category_ids = '2~3~4|2~3~4';
       _edrone.product_category_names = 'Główna~Shoes~Womens shoes|Główna~Shoes~Womens shoes';
       _edrone.product_counts = '1|3';
       _edrone.order_id = '4321';
       _edrone.country = 'Polska';
       _edrone.city = 'Kraków';
       _edrone.base_currency = 'PLN';
       _edrone.order_currency = 'PLN';
       _edrone.base_payment_value = '671.50';
       _edrone.order_payment_value = '671.50';
</script>

Order cancel
The "order_cancel" event allows marking orders in edrone CRM system as deleted.


<script type="text/javascript">
       _edrone.app_id = '51a97611a3430';
       _edrone.version = '1.0.0';
       _edrone.email = 'jan.kowalski@edrone.me';
       _edrone.action_type = 'order_cancel';
       _edrone.order_id = '4321';
       _edrone.platform_version = '1.1.26';
       _edrone.platform = 'prestashop';
</script>

Subscribe


<script type="text/javascript">
       _edrone.app_id = '51a97611a3430';
       _edrone.version = '1.0.0';
       _edrone.action_type = 'subscribe';
       _edrone.platform_version = '1.1.26';
       _edrone.platform = 'prestashop';
       _edrone.email = 'jan.kowalski@edrone.me';
       _edrone.subscriber_status = '1';
</script>


Other information

Google Tag Manager
Currently not supporting

In case implementing edrone integration on test enviroment, after publishing integration to production create new edrone account and use new App_id.

Log in

Log in Forgot password? ×

edrone 30 days free trial

no credit card required

Join us Forgot password? ×