Fortifi Developer Guide

Introduction

You can get the library using Composer by including the following in your project's composer.json requirements and running composer update:

If you're not using Composer for your package management, you can browse and download the library from GitHub at https://github.com/fortifi/sdk

php composer.phar require fortifi/sdk:~2.0

    - OR -

"require": {
  ...
  "fortifi/sdk" : "~2.0"
  ...
}

Authentication

Authentication to the Fortifi system is provided in the Fortifi SDK via OAUTH2.

To instantiate a Fortifi API Instance, you will need to provide your unique Organisation FID and the API User & Secret details.

This instance can then used for all additional calls to the API.

use Fortifi\Sdk\Fortifi;

...

$provider = Fortifi::getInstance(
'org_fid',
'api_user',
'api_secret'
);

...curl -H "X-Fortifi-Org: ORGFIDGOESHERE" -X POST\
"http://api.fortifi.co/oauth/access-token" -d\
"grant_type=service_account&api_key=API-KEY-GOES-HERE&api_user=API-USER-GOES-HERE"

Inbound Links

Before you can get started with your new affiliate system, you will need to configure two hostnames to point to our servers, to provide your tracking links (url.) and your advertiser portal (advertisers.). Due to calls required through the tracking lifecycle, you must apply these DNS entries on the domain of your product. If you are running multiple products, you should have the entries on each domain.

advertisers.youdomain.tld > CNAME > advertisers.fortifi.zone

url.yourdomain.tld > CNAME > url.fortifi.zone

Although these are the defaults, you can choose one of the following alternatives for your hostname.

Default Hostname Alternative Hostnames CNAME
advertisers affiliates. aff. affiliate. advertisers.fortifi.zone
url. track. link. click. url.fortifi.zone

Device Fingerprinting

Device Fingerprinting is used to record details about your visitor and the device they use to navigate around your website.

To utilise this functionality, you will need to add an additional javascript file to the bottom of your web pages, as follows*:

<!-- Start of Fortifi Code -->
 <script type="text/javascript">
   (function(d,s,i,u) {
     if (d.getElementById(i)){return;}
     var n=d.createElement(s),e=d.getElementsByTagName(s)[0];
     n.id=i;n.src='//'+u+'/fp/init/fortifi.js';
     e.parentNode.insertBefore(n, e);
   })(document,"script","fortifi-track","url.your-domain.com");
 </script>
<!-- End of Fortifi Code -->

* Change your-domain.com to your actual domain name.

Visitors

Visitor actions are triggered via the SDK Visitor Model.

All visitor actions are triggered through either the triggerAction or reverseAction methods.

use
Fortifi\FortifiApi\Affiliate\Enums\AffiliateBuiltInAction;
use Fortifi\FortifiApi\Affiliate\Enums\ReversalReason;

...

// get visitor id
$visitorId = $provider->getVisitorIdCookie();

...

// get visitor details using id
$visitor = $provider->visitor($visitorId);

...

// trigger an action
$action = $provider->visitor()->triggerAction(
'companyId',
'actionKey', // AffiliateBuiltInAction
'transactionId',
'transactionValue',
'dataArray',
'couponCode',
'returnPixels',
'userReference'
);

...

// reverse an action
$reversal = $provider->visitor()->reverseAction(
'transactionId',
'originalAction', // AffiliateBuiltInAction
'reason', // ReversalReason
'reversalId',
'reversalAmount',
'dataArray'
);

...

// get visitor pixels
$pixels = $provider->visitor()->getPixels();

...
#Triggering an action

curl -i \
-H "X-Fortifi-Org: ORGFIDGOESHERE" \
-H "Authorization: Bearer tFQubw3MxmY4030AAZvAiR30dQE7sZLQbv1KWdQc" \
-H "Content-Type: application/json" \
-X POST \
"http://api.fortifi.co/affiliate/action/post" \
-d \
"{\"actionKey\":\"acquisition\",\"transactionId\":\"ORDER-1234\",\"transactionValue\":10.00,\"coupon\":null,\"returnPixels\":true,\"companyFid\":\”COMPANYFIDGOESHERE\",\"visitorId\":null,\"userReference\":\"USER-123\",\"userAgent\":null,\"language\":null,\"encoding\":null,\"clientIp\":\"8.8.4.4\"}"

Customers

Customer data is used for messenger to communicate with your customers, and also within support to link tickets to a single customer.

use Fortifi\FortifiApi\Affiliate\Enums\AffiliateBuiltInAction;

...

// create a new customer (and trigger a lead)
$customer = $provider->customer()->create(
  'companyFid',
  'email',
  'firstName',
  'lastName', // optional
  'phoneNumber', // optional
  'yourReference' // optional
);

...

//Updating a customer


//Customer FID applied to this customer object, for future requests do:
$customer = $fortifi->customer('CustomerFid');

...


//Writing a custom property
$customer->setValue('custom_property','property value');

...


//Set a custom flag
$customer->setFlag('custom_flag',true);

...


//Custom Counters
$customer->incrementCounter('custom_counter',2);
$customer->decrementCounter('custom_counter',1);


        

Support / Knowledgebase

To make your public knowledgebase available for your customers, you must configure your domain to point to the fortifi system.

You can do this by adding a single CNAME record.

support.youdomain.tld > CNAME > support.fortifi.zone

Although these are the defaults, you can choose one of the following alternatives for your hostname.

Default Hostname Alternative Hostnames CNAME
support. support. help. knowledge. support.fortifi.zone
mail. - mail.fortifi.zone

Support / Live Chat

To make direct chat available for your customers, you must configure your domain to point to the fortifi system.

You can do this by adding a single CNAME record.

chat.youdomain.tld > CNAME > chat.fortifi.zone

Although these are the defaults, you can choose one of the following alternatives for your hostname.

Default Hostname Alternative Hostnames CNAME
chat. chat. livechat. chat.fortifi.zone

To start using Fortifi Chat on your site, simply add the following code.

<!-- Start of Fortifi Chat config -->
<script>
  window.addEventListener(
    'ready.fortifichat', function ()
    {
      fortifiChat.manager.createInstance(
        {
          //Chat Configuration Goes Here
        }
      );
    }
  );
</script>
<!-- End of Fortifi Chat config -->
<!-- Start of Fortifi Chat code -->
<script type="text/javascript">
  (function (d, s, i)
  {
    if (d.getElementById(i)){return;}
    var n = d.createElement(s), e = d.getElementsByTagName(s)[0];
    n.id = i;
    n.src = 'https://chat.fortifi.io/js/chatManager.js';
    e.parentNode.insertBefore(n, e);
  })(document, "script", "fortifi-chat");
</script>
<!-- End of Fortifi Chat code -->

You can modify the behaviour and look of Fortifi Chat on your site by adding any or all of the following configuration options:

<script>
  fortifiChat.manager.createInstance(
  {
      soundEnabled:     true,                 //boolean, enables sound effects on message
      startMaximised:   true,                 //boolean, popup opens on page load
      maximisedWidth:   420,                  //int
      maximisedHeight:  550,                  //int 
      brandColour:      '#428BCA',            //string, hex value for brand elements
      actionColour:     '#5cb85c',            //string, hex value for button colour
      callToActionText: 'How can we help?',   //string, max 20 characters
      isEmbeded:        false,                //boolean, embed chat into a div on the page 
      embedDivId:       null,                 //string, id of element to embed chat into
      welcomeText:      'Tell us a little about yourself before we start chatting...'                 //string, max 200 characters
      departments:      [                     //array or null, (see *)
              {
                "fid":  "FID:DEP:0123456789:abcdefghijklm",
                "name": "Department One"
              },
              {
                "fid":  "FID:DEP:0123456789:abcdefghijklm",
                "name": "Department Two"
              },
              {
                "fid":  "FID:DEP:0123456789:abcdefghijklm",
                "name": "Department Three"
              },
      ]
  });
  </script>

(*) Departments Field:
If is not present then the organisation defaults will be used.
If is an empty array ([]), org defaults will be ignored and no department will be selected.
If is only set with one department name and fid, then all chats will route to that department, but the dropdown on the chat interface will not be displayed.
If there are more than one department name and fid set, then these will appear in the drop down.
More than one department can be assigned to the same fid

This details the Chat Config options available for Customers to customise chat on individual pages