purlhub

Support Center

purlService JSAPI v1.5

Last Updated: Mar 06, 2014 08:48PM MST

The purlService JSAPI is a proprietary service that dynamically drives Landing Page personalization via your campaign list data, and Personalized URL (PURL) resolution via unique URLs in an event driven manner.  Our API or Personalization Driver, leverages simple HTML constructs and binds your campaign list data objects to the Document Object Model (DOM) and renders a dynamically personalized view.

In MVC context, the "Model" is your campaign list data available via your purlHub account portal;  the "Controller" is our JSAPI library purlServiceApi.min.js and purlService JavaScript object; and the "View" is your HTML landing page.

Including the JSAPI library:

Include the source JSAPI library purlService.min.js and add the a minimal JavaScript initialization code to the HTML HEAD (preferred) section of each HTML page of your micro-site, enabling personalization.  

<link type="text/css" rel="stylesheet" media="screen" href="http://library.cdn.purlhub.com/purlHub.css" />
<script type="text/javascript" src="http://api.purlhub.com/JSAPI/purlServiceApi.min.js?vz=1502">
</script>

<script type="text/javascript">

    var options = {
        pageName: 'My pURL Landing Page',
        serviceToken: '{your campaign service token}'
    };

    purlService.init(options);

</script>
 

JSAPI Options: purlService.init( [object|string] )

purlService initialization is invoked by the "init" method, passing the configuration as the only parameter.  This can be either of an Object containing options in the form of property and value, or simply a string containing your campaign serviceToken.  The latter assumes all default values.  

Options, defaults values and their purpose:

  • autoLoad: true 
    (bool) - Automatically fetch the purl data object.
     
  • autoRender: true 
    (bool) - Automatically render fetched data.
     
  • suppressPurlRedirect: false
    (bool) - If true, suppress redirecting the browser to the actual purl URL, if its not already in the address bar.  The default action when a new profile is created via landing page (registration/self-signup), is to redirect to the new PURL if no ongoing activity exists.  This option allows the designer to override this default behavior.
     
  • autoCaptureProfiles:true
    (bool) - Enable or disable the internal automatic data-capture submit handler call on profile forms.  Useful to prevent double submissions when manually calling purlHub utility methods per the outcome of some custom processing.
     
  • autoCaptureRecords: true
    (bool) - Enable or disable the internal automatic data-capture submit handler call on record forms.  Useful to prevent double submissions when manually calling purlHub utility methods per the outcome of some custom processing.
     
  • codeGenMetaFormat: 'firstName:lastName:alphaNum.L2'
    (string) - format string to use for defining purlCode generation during new profile creation via landing page form (registration/self-signup). 
    see complete documentation...
     
  • renderNullValues: true
    (bool) - true = overwrite textNodes with empty strings (null values) during data render, false = ignore null values and empty strings during data render.
     
  • renderFlashVars: fasle
    (bool) - During data render, attempt to update any embedded flash object's param node (matching the class flag prefix + "-flashVars") with the object data as var=value.  (Note: forces a re-load of the flash object, post HTML render)
     
  • profileFormIdPrefix: 'phProfileForm' 
    (string) - ID prefix to identify the HTML Form element to bind with the purl profile data-object (optionally followed by a - or _ and any string). 
     
  • profileDataClassPrefix: 'phProfileData' 
    (string) - Class Flag prefix to identify HTML elements to bind to purl profile data points  (capture and/or render).  Class Flags follow the form of {prefix}-{propertyName}.
     
  • profileShowClass: 'phProfileShow' 
    (string) - Class Flag that identifies content blocks or elements to toggle display on, if a valid pURL Profile is present.  Requires purlHub.css base skin. 
     
  • recordFormIdPrefix: 'phRecordForm' 
    (string) - ID prefix to identify the HTML Form element to bind with a named purl record data-object (must be followed by a - or _ and name of the record). 
     
  • recordDataClassPrefix: 'phRecordData'
    (string) - Class Flag prefix to identify HTML elements to bind to named purl record data points (capture and/or render).  Class Flags follow the form of {prefix}-{recordName}-{propertyName}. 
     
  • recordShowClassPrefix: 'phRecordShow'
    (string) - Class Flag prefix defining the form of {prefix}-{recordName} class names that identify content blocks or elements to toggle display on, if a valid pURL Profile is present and it contains the named record object.  Requires purlHub.css base skin.  
     
  • attributeDataClassPrefix: 'phAttributeData'
    (string) - Class Flag prefix to identify HTML elements bind to purl attribute data points (capture and/or render). 
     
  • referralFormIdPrefix:  'phReferralProfileForm'
    (string) - ID prefix to identify the HTML Form element to bind with the purl "referral" profile data-object (optionally followed by a - or _ and any string).  This enables profile (A) to "refer-a-friend" by submitting a "referral" form; creating profile (B) with the appropriate referrer association.
     
  • referralDataClassPrefix:
    (string) - Class Flag prefix to identify HTML elements to bind to purl "referral" profile data points  (capture and/or render).  Class Flags follow the form of {prefix}-{propertyName}.
     
  • referrerDataClassPrefix:
    (string) - Class Flag prefix to identify HTML elements to bind to the associated "referrer" purl profile (purlReferrer property) data points  (render only).  Class Flags follow the form of {prefix}-{propertyName}.  Supports mentioning the referrer on personalized pages.
     
  • associationDataClassPrefix:  'phAssociatedData'
    (string) - Class Flag prefix to identify HTML elements to bind to the associated parent purl profile (purlParent property) data points  (render only).  Class flag follows the form of {prefix}-{propertyName}.
     
  • purlCode: null 
    (string) - By default the purlCode is auto-detected per-config by either (1) the last path component of the URI for path based PRULs, (2) a fragment of the sub-domain for Sub-Domain based pURLs , or (3) the last detected purlCode remembered from a prior visit.  If the Query String parameter '_purl'  is detected, its value supersedes the preceding auto-detection methods.  This option allows the integrator the explicitly set the purlCode, bypassing auto-detection.
     
  • purlCodeSitckyDays: 90
    (integer)  - Sets the number of days that the last used purlCode will be remembered by the browser. 
     
  • fileNamesIgnore: ""
    Literal file name path components to ignore during path based purlCode auto-detection (comma and/or whitespace delimited list).  This supplements the default behavior; file names are always excluded by matching against known file extensions (*.php, *.html, *.css, *.js ...). Only applies when subDomainMode is disabled. 
     
  • caseSensitiveResolution: false 
     (bool) - Whether or not purlCode lookups are resolved case sensitively or not.  This option is forced to false when  the option subDomainMode is true.
     
  • serviceToken: null 
     (string) - The access service token associated with the purlHub campaign. **REQUIRED**
     
  • queryStringMode: false | permissive 
    (bool), (enforcing | permissive) - When TRUE or 'enforcing' purlCode auto-detection exclusively uses the Query String parameter "_purl", disabling core methods and falling back on Browser Cookies.  When FALSE or 'permissive', purlCode auto-detection uses the core methods, but allows the Query String parameter "_purl=" to override the detected code.
     
  • resetService: false
     (bool) - A debugging feature...  Clears remembered purlCode upon initialization and falls back on purlCode URL detection process. 
     
  • subDomainMode: false
    (bool) - Enable or disable sub-domain based purlCode auto-detection.  When true (enabled), this option disables the path based purlCode auto-detection and defaults to extracting the purlCode from the 3rd component from the right of the domain name.  (i.e. JohnSmithX2.mySite.com)
     
  • subDomainPos: 3
    (integer) - position from the right of the domain name components to extract the purlCode from.  Only applies when subDomainMode is enabled. 
     
  • subDomainsIgnore: "www, m"
    Domain name fragments to ignore, to be considered as common names, during sub-domain purlCode auto-detection (comma and/or whitespace delimited list).  Only applies when subDomainMode is enabled. 
 

URL & Query String Params:


The following Query String parameters, if present in the URL, have special meaning. 
 
  • _phReferrer: null
    URL parameter to set as this profile's purlReferrer property.  If present and a valid relative reference to another profile, the current personalization profile is updated with this value.  if the current session is anonymous, this value is remembered via a session cookie to support page navigation prior to conversion.   
     
  • _phResetService: null
    if either true, 1, or yes - sets the purlService Config Option "resetService", and the purlTracker Config Option "resetTracker" to true.  Having the effect of forgetting all remembered (persistent) information (tracking IDs, purlCode,...)
 

JSAPI Public Methods:  purlService.{method}(parameters)

Note: [ ] designates optional arguments.  The autoLoad, autoRender, autoCaptureProfiles, and autoCaptureRecords option(s) (default=enabled) control automatic integration of all personalization data (profile, records, attributes, associations, referrals).  The get* and save* methods are provided for developer utility use, and not required for standard purl integration.

  • init(options)
    JSAPI initializer (the fundamental prerequisite to purlHub integration).  Parameter can be either a string representing the serviecToken OR an options object. Handles DOM readiness internally, includes and initializes the PH Tracking API library with cascading options.
     
  • setOption(name, value)   
    Set any of the JSAPI config option, post init() call. 
     
  • getPurlProfile(purlCode, [callback, scope])
    Manually retrieve and render a purl profile w/ an optional inline callback function and scope.
     
  • savePurlProfile([callback, scope])
    Save a purl profile object via DOM extraction.  Prerequisites: init() must be complete, and a properly setup profile form, identified by the "profileFormIdPrefix", must exist in the DOM.
     
  • savePurlReferralProfile([callback, scope])
    Save a purl "referral" profile object via DOM extraction.  Referring-A-Friend, either anonymously or from a personalized visit.  Prerequisites: init() must be complete, and a properly setup "referral" profile form, identified by the "referralFormIdPrefix", must exist in the DOM.
  • getPurlRecord(recordName, [callback, scope])
    Retrieve and render a purl record w/ an optional inline callback function and scope.  Prerequisites: init() must be complete, and a purlCode must be established.
     
  • savePurlRecord(recordName, [callback, scope])
    Save a purl record w/ an optional inline callback function and scope.  Prerequisites: init() must be complete, and a properly setup record form, identified by the "recordFormIdPrefix", must exist in the DOM.
     
  • getPurlAttribute(attributeName, [callback, scope])
    Retrieve and render a purl attribute w/ an optional inline callback function and scope.  Prerequisites: init() must be complete, and a purlCode must be defined.
     
  • savePurlAttribute(attributeName, value, [callback, scope])
    Save a purl attribute w/ an optional inline callback function and scope.  Prerequisites: init() must be complete.  Supports increment operators in string form: '++', '--', '{increment}', '{deincrement}'.
     
  • savePurlReferrerAttribute(attributeName, value, [callback, scope])
    Save a purl "referrer" attribute (an attribute of the purlReferrer) w/ an optional inline callback function and scope.  Prerequisites: init() must be complete, and a valid purlCode must be established.
 

JSAPI Events: (callbacks and their arguments)

  • onAnonymous: function()
    A previously defined, or anonymous JavaScript function to execute when the purl is undefined or anonymous.
     
  • onPurlLoad:  function(dataObj, purlServiceResponseObj, eventName)
    A previously defined, or anonymous JavaScript function to execute after a successful purl load.
     
  • onPurlLoadError: function(errorObj) 
    A previously defined, or anonymous JavaScript function to execute after an un-successful purl load.
     
  • onPurlSave: function(dataObj, purlServiceResponseObj, eventName)
    A previously defined, or anonymous JavaScript function to execute after a successful purl save.
     
  • onPurlSaveError: function(errorObj) 
    A previously defined, or anonymous JavaScript function to execute after an unsuccessful purl save.
     
  • onRecordLoad:  function(dataObj, purlServiceResponseObj, eventName)
    A previously defined, or anonymous JavaScript function to execute after a successful purl record load.
     
  • onRecordLoadError: function(errorObj) 
    A previously defined, or anonymous JavaScript function to execute after an unsuccessful purl record load.
     
  • onRecordSave: function(dataObj, purlServiceResponseObj, eventName)
    A previously defined, or anonymous JavaScript function to execute after a successful purl record save.
     
  • onRecordSaveError: function(errorObj) 
    A previously defined, or anonymous JavaScript function to execute after an unsuccessful purl record save.
     
  • onAttributeLoad: function(dataObj, purlServiceResponseObj, eventName)

     

    A previously defined, or anonymous JavaScript function to execute after a successful purl attribute load.
     
  • onAttributeLoadError: function(errorObj) 
    A previously defined, or anonymous JavaScript function to execute after an unsuccessful purl attribute load.
     
  • onAttributeSave: function(dataObj, purlServiceResponseObj, eventName) 
    A previously defined, or anonymous JavaScript function to execute after a successful purl attribute save.
     
  • onAttributeSaveError: function(errorObj) 
    A previously defined, or anonymous JavaScript function to execute after an unsuccessful purl attribute save.
     
  • onReferrerAttributeSave: function(dataObj, purlServiceResponseObj, eventName)
    A previously defined, or anonymous JavaScript function to execute after a successful purl referrer attribute save.
     
  • onReferrerAttributeSaveError: function(errorObj) 
    A previously defined, or anonymous JavaScript function to execute after an unsuccessful purl referrer attribute save.
     
  • onPurlReferralSave: function(dataObj, purlServiceResponseObj, eventName)
    A previously defined, or anonymous JavaScript function to execute after a successful purl referral save..
     
  • onPurlReferralSaveError: function(errorObj) 
    A previously defined, or anonymous JavaScript function to execute after an unsuccessful purl referral save.
     

Contact Us

  • Post a Public Question
  • Ask the Community
  • Email Us

Recent Discussions

Ajax-loader-small