Event

Events Overview

An Event is the measurable action you wish to take place. When the event happens, the commission is earned.

Who is an Event for?

An event is determined by the Company who creates the campaign. The affiliate should clearly know what event you want to take place so they can promote your company properly.

What is an Event?

An event is a measurable action. Typically, this is a sale of goods or services. It may also be a user registration or email opt-in.

Where do I define the Event?

You determine the event during the campaign creation process.

When do I define an Event?

You define the event during the campaign creation process. There, you will determine what you are willing to pay as commission when your event takes place.

Why do I need to determine multiple Events?

You don't. However, many companies choose to create campaigns which provide rewards for different Events. For example, a company may reward a 25% commission for a referred sale and a $5 commission for a new registered user.

How do I get the value of the "referer" parameter?

You get it from the cookie which you set on the landing page(s).
On each landing page specified in either a campaign or marketing tool (ad), you should retrieve the value of the 'zref' parameter. It will be passed in GET or POST depending on the settings: (https://zferral.com/profile/api).
The value of 'zref' parameter will look like this: 018bf22aad56842ee823bd925052eb0c%2C1325480400
It consists of two values separated by a comma. The first is a hashed value of the cookie to be set. The second is an expiration date of this cookie.
Simply follow the below snippet of code (it is provided in PHP -- you may need to alter it for a different web language).

    if (!isset($_COOKIE['hash']) || $_COOKIE['hash'] == '0')
    {
      $zref = (isset($_GET['zref']) ? $_GET['zref'] : (isset($_POST['zref']) ? $_POST['zref'] : '0'));
      $zref = explode(',', rawurldecode($zref));
      $hash = $zref[0];
      $dateExpire = ($dateExpire ? strtotime($dateExpire) : isset($zref[1]) ? $zref[1] : 0);
      setrawcookie('hash', $hash, $dateExpire, '/');
    }

Methods:

• call
• batchCall

Examples:

• call
• batchCall

All of the event attribute fields are returned from GET (read) operations. Only those attributes not marked as read only may be set via POST (create) or PUT (update) operations.

Parameters for call() method:

• campaign_id INT (Required) Campaign ID
• revenue DOUBLE(10,2) (Required) It defines the total value of your customer’s order
• customer_id VARCHAR(255) (Required) It is a unique id of the customer in your system
• affiliate_id INT (Optional/Required) Affiliate ID. AffialiteID if given, it is NOT get Referer or Coupon
• coupon CHAR(15) (Optional/Required) Coupon. If you use the Coupon is AffiliateId get on the basis of
• referer CHAR(32) (Optional/Required) Affiliate referrer. It's passed in the affiliate link as 'zref'. Explained here.
• ignore_cookie BOOL (Optional) Enable/Disable recurring commissions. Allow true values: 'true', 't', 'yes', 'y', 'on', '1'. Default disabled
• unique_id VARCHAR(255) (Optional) An parameter that is unique (i.e. order id, payment id or something similar). Required for detection of "duplicate events"
• services_id VARCHAR(255) (Optional) It is a unique id of the service/article that was bought
• affiliateRemote_id INT (Optional) Remote Affiliate ID
• info VARCHAR(255) (Optional) Any description
• debug BOOL (Optional) Debug mode. Allow true values: 'true', 't', 'yes', 'y', 'on', '1'. Default disabled

Methods

call - Usage Example

Scenarios [examples]:

1. Scenario: Call event [debug mode] (sending all required parameters)

   Request

   a) XML

           <?xml version="1.0" encoding="UTF-8"?>
           <event>
             <debug>1</debug>
             <campaign_id>12</campaign_id>
             <revenue>253.1</revenue>
             <customer_id>33</customer_id>
             <referer>be290e41b7eee0af6b30f2ef68aaac3c</referer>
           </event>
         

   b) JSON

           {
            "event" : {
               "debug"       : 1,
               "campaign_id" : 12,
               "revenue"     : 253.1,
               "customer_id" : '33',
               "referer"     : 'be290e41b7eee0af6b30f2ef68aaac3c'
           }}
         

   
   

   Response (return status code "200 OK"):

   a) XML

           <?xml version="1.0" encoding="UTF-8" ?>
           <event>
             <commission_sum>45.4</commission_sum>
           </event>
         

   b) JSON

           {
            "event" : {
               "commission_sum" : 45.4
           }}
         

   
   

2. Scenario: Call event [debug mode] (send non-existent campaign_id)

   Request

   a) XML

           <?xml version="1.0" encoding="UTF-8"?>
           <event>
             <debug>1</debug>
             <campaign_id>43</campaign_id>
             <revenue>253.1</revenue>
             <customer_id>33</customer_id>
             <referer>be290e41b7eee0af6b30f2ef68aaac3c</referer>
           </event>
         

   b) JSON

           {
            "event" : {
               "debug"       : 1,
               "campaign_id" : 43,
               "revenue"     : 253.1,
               "customer_id" : '33',
               "referer"     : 'be290e41b7eee0af6b30f2ef68aaac3c'
           }}
         

   
   

   Response (return status code "200 OK"):

   a) XML

           <?xml version="1.0" encoding="UTF-8" ?>
           <event>
             <error>Campaign with id = 43 does NOT exist.</error>
           </event>
         

   b) JSON

           {
            "event" : {
              "error" : "Campaign with id = 43 does NOT exist."
           }}
         

   
   

3. Scenario: Call event [debug mode] (send twice the same event, with the same unique_id)

   Request

   a) XML

   The first event:

           <?xml version="1.0" encoding="UTF-8"?>
           <event>
             <debug>1</debug>
             <campaign_id>43</campaign_id>
             <revenue>253.1</revenue>
             <customer_id>33</customer_id>
             <unique_id>104kfs83js8</unique_id>
             <referer>be290e41b7eee0af6b30f2ef68aaac3c</referer>
           </event>
         

   The second event:

           <?xml version="1.0" encoding="UTF-8"?>
           <event>
             <debug>1</debug>
             <campaign_id>43</campaign_id>
             <revenue>253.1</revenue>
             <customer_id>33</customer_id>
             <unique_id>104kfs83js8</unique_id>
             <referer>be290e41b7eee0af6b30f2ef68aaac3c</referer>
           </event>
         

   b) JSON

   The first event:

           {
            "event" : {
               "debug"       : 1,
               "campaign_id" : 43,
               "revenue"     : 253.1,
               "customer_id" : '33',
               "unique_id"   : '104kfs83js8'
               "referer"     : 'be290e41b7eee0af6b30f2ef68aaac3c'
           }}
         

   The second event:

           {
            "event" : {
               "debug"       : 1,
               "campaign_id" : 43,
               "revenue"     : 253.1,
               "customer_id" : '33',
               "unique_id"   : '104kfs83js8'
               "referer"     : 'be290e41b7eee0af6b30f2ef68aaac3c'
           }}
         

   
   

   Response (return status code "200 OK"):

   a) XML

   The first response:

           <?xml version="1.0" encoding="UTF-8" ?>
           <event>
             <commission_sum>45.4</commission_sum>
           </event>
         

   The second response:

           <?xml version="1.0" encoding="UTF-8" ?>
           <event>
             <error>Duplicate event.</error>
           </event>
         

   b) JSON

   The first response:

           {
            "event" : {
               "commission_sum" : 45.4
           }}
         

   The second response:

           {
            "event" : {
              "error" : "Duplicate event."
           }}
         

   
   

4. Scenario: Call event [debug mode] (send campaignId different from campaignID referer)

   Request

   a) XML

           <?xml version="1.0" encoding="UTF-8"?>
           <event>
             <debug>1</debug>
             <campaign_id>10</campaign_id>
             <revenue>253.1</revenue>
             <customer_id>33</customer_id>
             <unique_id>104kfs83js8</unique_id>
             <referer>be290e41b7eee0af6b30f2ef68aaac3c</referer>
           </event>
         

   b) JSON

           {
            "event" : {
               "debug"       : 1,
               "campaign_id" : 10,
               "revenue"     : 253.1,
               "customer_id" : '33',
               "unique_id"   : '104kfs83js8'
               "referer"     : 'be290e41b7eee0af6b30f2ef68aaac3c'
           }}
         

   
   

   Response (return status code "200 OK"):

   a) XML

           <?xml version="1.0" encoding="UTF-8" ?>
           <event>
             <error>Strict commissions enabled.</error>
           </event>
         

   b) JSON

           {
            "event" : {
              "error" : "Strict commissions enabled"
           }}