bg4

API & Docs |

View Documentation &
Explore our RESTful API

purlService API 2017-06-26T21:07:19+00:00

purlService API

Options

autoLoad: true
Automatically fetch the purl data object. (bool)
autoRender: true
Automatically render fetched data. (bool)
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).
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: false
(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

_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,…)

Methods

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.

Events

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.