HOLD AT LOCATION
SHOPPING CART WIDGET
RETAILER INTEGRATION GUIDE
Use of the FedEx HAL Shopping Cart Widget and this Retailer Integration Guide
is governed by the FedEx Hold At Location End User License Agreement
Version: 1.8
November 18, 2016
VERSION AND REVISION HISTORY
HAL Shopping Cart Widget
Revision: 1.8
Retailer Integration Guide
Issue Date: 09/30/2016
TABLE OF CONTENTS
1 Introduction .......................................................................................................................................... 3
2 HAL Shopping Cart Widget Overview.................................................................................................. 3
3 Web Page Setup ................................................................................................................................... 3
3.1
Add jQuery (Required) ....................................................................................................... 3
3.2
Add HAL Shopping Cart Widget and CSS (Required)......................................................... 4
3.3
Add FedExHALWidget HTML div Tag (Required) ............................................................... 4
3.4
Instantiate FedExHALWidget (Required) ........................................................................... 4
3.5
Provide your Domain Names (Required) .......................................................................... 4
3.6
Sign and Return End User License Agreement (EULA) (Required)................................... 5
3.7
Set Widget Parameters (Optional) .................................................................................... 5
4 Execute a Location Search ................................................................................................................... 8
5 Get Selected HAL Location .................................................................................................................. 9
6 Selected HAL Location and FedEx Shipment Creation Workflow Integration ................................ 10
Appendix A: HAL JSON Output Format ..................................................................................................... 11
Appendix B: HAL XML Output Format ...................................................................................................... 12
Appendix C: Sample Web Page HAL Integration ...................................................................................... 13
Appendix D: HAL Widget URLs .................................................................................................................. 15
Appendix E: Contact Information and Support Level............................................................................... 16
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 2 of 16
1.
INTRODUCTION
This document describes how a retailer can properly integrate the FedEx Hold At Location Shopping Cart Widget (hereinafter
referred to as the “HAL Widget”) into their e-commerce website and existing FedEx shipping workflow.
2.
OVERVIEW OF THE FEDEX HAL SHOPPING CART WIDGET
The HAL Widget is a self-contained web component that provides FedEx location search, location mapping, and location
selection capabilities.
When a location search is performed using the HAL Widget, it will locate and display FedEx locations that support the Hold
at FedEx Location option. Location specific details such as the name of the location, location address, hours of operation,
and distance from source address will be displayed in both list and map views. Using the location details and map, your
online shopper can select the HAL location that best fits their location delivery and availability needs. Once a location is
selected, the HAL widget formats the selected location details and outputs the location for your consumption and
incorporation into your existing FedEx® shipping solution. Below is a screenshot of the HAL Widget with the hold at location
search results.
Figure 1.0 – The FedEx HAL Shopping Cart Widget user interface
3.
REQUIRED STEPS FOR WEB PAGE SETUP
3.1 Add jQuery (Required)
The HAL Widget has a dependency on the jQuery JavaScript library version 1.11.3. In order to create this necessary relationship,
you must add jQuery to the target web page that will contain the HAL Widget. Below is a code snippet that shows how jQuery
is included on a web page.
<script
src="https://code.jquery.com/jquery-1.11.3.js"></script>
NOTE: Completion of this step is required.
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 3 of 16
NOTE: If the target web page already has a jQuery reference, you should not use multiple jQuery references. Please ensure
that the jQuery version is greater than or equal to 1.11.3.
3.2 Add HAL Shopping Cart Widget and CSS (Required)
The HAL Widget is comprised of two (2) resources. The resources are as follows:
•
hal.js - JavaScript
•
hal.css - cascading style sheet
Similarly to how other JavaScript resources are used, the two (2) resources must be added to the target web page. Below is a
code snippet that shows you how to include the resources on the target web page.
<link
rel="stylesheet"
<script
href="../hal/hal-1.0.0.css">
src="../hal/hal-1.0.0.js"></script>
NOTE: Completion of this step is required.
NOTE: Please consult Appendix D and/or the HAL Widget development team for the absolute URLs for the most current version
of the HAL Widget JavaScript and CSS resource files.
NOTE: The HAL Widget style can be customized (using CSS inline style or CSS self-hosting) to fit your needs.
3.3 Add FedExHALWidget HTML div Tag (Required)
In order to define the page location and render the HAL Widget, a HTML div tag with the identifier “FedExHALWidget” must
be added to your target web page. Below is a code snippet that shows how to include the FedExHALWidget div tag on your
page.
<div
id="FedExHALWidget"></div>
NOTE: Completion of this step is required.
3.4 Instantiate FedExHALWidget (Required)
You must create a FedExHALWidget object instance. FedExHALWidget object instantiation can be performed by invoking
the constructor of the fully qualified FedExHALWidget. The code snippet below shows how to instantiate the
FedExHALWidget.
var FedExHALWidget = fedex.hal.FedExHALWidget();
NOTE: Completion of this step is required. A sample of web page HAL integration is set forth in Appendix C.
3.5 Provide your Domain Names (Required)
You must provide a domain name to FedEx for the website(s) within which you will integrate the HAL Widget. This is needed
in order to enable your website to call location mapping information.
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 4 of 16
When you know the Test and Production domain names you will use to call the HAL Widget, please send an email of those
names to [email protected] requesting that they be added to the HAL domain list.
NOTE: Completion of this step is required.
3.6 Sign and Return Terms of Use Agreement (Required)
This step requires your acceptance of the HAL Widget Terms of Use Agreement. Please click on the following link to access a
copy of the Agreement:
http://fedex.com/us/services/pdf/HAL_Shopping_Cart_Widget_EULA.pdf
Download the Agreement, print it, sign it, scan it and return it to FedEx via email at [email protected].
NOTE: Completion of this step is required.
3.7 Set Widget Parameters (Optional)
You may also specify optional HAL Widget parameters that can be passed to an instance of the widget prior to page rendering
and the execution of a location search. The desired parameters that can be configured are as follows:
Property Name
Property Value
An array of positive whole number values. The
maximum value is 100.
searchRadiusOptions
For example: [5, 10, 15, 20, 25, 50, 100]
If not set, then the component uses [5, 10, 15,
20, 25, 50, 100].
defaultSearchRadiusOption
This is one of the values of the
searchRadiusOptions property.
If not set, then the component uses 5.
A string.
title
If not set, the component uses "Select a FedEx
Hold-at-Location".
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 5 of 16
Description
This parameter is used to
set the search radius dropdown list in the component
UI.
This parameter must be
used before the UI is
created to take effect.
This parameter is used to
set the default search
radius in the search radius
drop-down list in the
component UI.
This parameter must be
used before the UI is
created to take effect.
This parameter is used to
set the title of the
component UI.
This parameter must be
used before the UI is
created to take effect.
Property Name
maxResultsRequested
Property Value
A positive whole number.
If not set, the component uses 50.
Description
This parameter sets the
maximum number of
locations the component
back- end service provides.
This parameter can be set
anytime. It will take effect
when the next search for
hold- at locations is
executed.
(This may be different from
the number of locations
displayed, as there may be
fewer locations found or
front-end filtering such as
state filtering can reduce
the number of locations
displayed.)
An enumerated value.
It controls the type of locations included in the
location list.
locationTypeFilter
LOCATION_TYPE_FILTERS.FXO lists all the FedEx
Office locations including FedEx delivery sites
locations and FedEx Ship&Get® lockers.
LOCATION_TYPE_FILTERS.FXO_STAFFED lists
FedEx Office locations with FedEx Office staff.
If a value is not specified, the default is
LOCATION_TYPE_FILTERS.FXO.
This property controls what
location type of locations
are retrieved from the backend service. FedEx delivery
sites are retail partner
locations in selected cities.
FedEx Ship&Get® lockers are
currently in the Dallas, TX
and Memphis, TN areas.
An array of name/value pairs that specify state
filters for location search results.
LOCATION_ATTRIBUTE_FILTERS.STATE_PROVINCE
is the list of states/provinces in scope.
LocAttrTypeFilter
If FILTER_INCLUDE_EXCLUDE.FILTER_EXCLUDE is
specified, state/provinces specified in the
LOCATION_ATTRIBUTE_FILTERS.STATE_PROVINCE
array will be excluded from location search
results.
If FILTER_INCLUDE_EXCLUDE.FILTER_INCLUDE is
specified state/provinces specified in the
LOCATION_ATTRIBUTE_FILTERS.STATE_PROVINCE
array will be included in location search results.
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 6 of 16
This property controls the
inclusion/exclusion of
locations from location
search results.
Property Name
Property Value
Description
A Boolean value.
This value indicates whether a location selection
button is displayed in each location search result
rendered in the location search results list.
selectLocationButton
If the button is not present, location selection
will occur whenever the end-user selects a
location search result with the mouse pointer.
Acceptable values are true (button is displayed)
and false (button is not displayed).
The default is false.
A Boolean value.
enableAddressInputField
This value indicates whether the UI input location
search field is editable.
Acceptable values are true (field is editable) and
false (field is not editable).
The default is false.
The code snippet below shows you how to create and pass widget parameters to a FedExHALWidget instance.
var halParams = {
searchRadiusOptions: [1, 3, 10, 25], defaultSearchRadiusOption: 3,
enableAddressInputField: true,
title: "Select a FedEx Hold-at-Location for Free",
maxResultsRequested: 30,
enableAddressInputField : false,
locationTypeFilter: FedExHALWidget.LOCATION_TYPE_FILTERS.FXO_STAFFED,
// No
locker/outdoor locations
LocAttrTypeFilter:
// Attribute Filtering [
{name:
FedExHALWidget.LOCATION_ATTRIBUTE_FILTERS.STATE_PROVINCE,
value: ['MA', 'CO'], include:
FedExHALWidget.FILTER_INCLUDE_EXCLUDE.FILTER_EXCLUDE},
//{name: FedExHALWidget.LOCATION_ATTRIBUTE_FILTERS.STATE_PROVINCE,
include:
FedExHALWidget.FILTER_INCLUDE_EXCLUDE.FILTER_INCLUDE},
],
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 7 of 16
value:
'TX',
selectLocationButton:
false
};
FedExHALWidget.setParameters(halParams);
NOTE: Completion of step is optional.
4.
EXECUTE A LOCATION SEARCH
Once page setup, instantiation and desired parameters have been specified, the HAL widget should be ready to perform
location searches. To perform the location search, you will need to construct an address object and invoke the
findLocations(address) method on the FedExHALWidget API.
The findLocations(address) method finds the FedEx available hold at location sites within the desired proximity of the address
specified by the customer and displays those sites to the customer.
This method is an asynchronous operation meaning it starts the search and returns without waiting for the search to
complete.
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 8 of 16
The input parameter is an object that contains the following properties.
Property Name
Property Value
Description
streetLine1
A string such as 4200 Belt Line
The street address
city
A string such as Dallas
The name of the city
stateOrProvinceCode
A string such as TX
The state code as defined by USPS For example: AK
postalCode
A string such as 75080
The five digit postal code as defined by USPS
The code snippet below shows you how to invoke the findLocations(address) method for the specified address.
var FedExHALWidget = fedex.hal.FedExHALWidget (address);
var address = { streetLine1: "1 Lake Ave", city: " Colorado Springs",
stateOrProvinceCode: "CO", postalCode: "80906"};
FedExHALWidget.findLocations(address);
NOTE: If an empty or invalid address is specified, zero search results will be returned.
5.
GET SELECTED HAL LOCATION
When your customer selects a FedEx HAL eligible location through the component UI, the location search results list is expanded
to reveal location details for the location selected. Additionally, the associated marker on the geographical map will change to
a highlighted form and indicates the selected hold at location (see Figure 2.0).
Once a location has been selected, the customer will be able to see details about the location by specifying the output format
and calling the getSelectedHAL(outputFormat) method on the FedExHALWidget API.
Figure 2.0 – Illustrates what the HAL Widget looks like when a location is selected. The location selected is the location data the
widget will return.
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 9 of 16
You can retrieve the selected hold-at location information in different formats. The input parameter specifies the format.
Format
Description
Example
HAL_FORMAT.JSON
This format returns a JavaScript object of
properties.
See Appendix A: HAL JSON Output Format
HAL_FORMAT.XML
This format returns an XML snippet that is
compatible with hold-at location section of
the FedEx Web Services SOAP message.
See Appendix B: HAL XML Output Format
The code snippet below show you how to invoke the getSelectedHAL() method for the user selected location.
var FedExHALWidget = fedex.hal.FedExHALWidget();
var selectedHAL = FedExHALWidget.getSelectedHAL(FedExHALWidget.HAL_FORMAT.XML);
NOTE: Please ensure the selected HAL location details have been retrieved before order workflow continuation.
SELECTED HAL LOCATION AND FEDEX SHIPMENT CREATION WORKFLOW INTEGRATION
6.
Once the selected HAL location has been retrieved, the HAL address must be incorporated into your existing FedEx shipment
creation workflow in order to ensure that shipments and generated labels are systematically marked as HAL and denote that
this is a HAL shipment.
Our expectation is that you will now submit three (3) addresses to the back-end FedEx shipment solution that you’re using:
•
Shipping address (usually this is the address of your warehouse)
•
Billing / Recipient address (your Customer’s billing or normal delivery address)
•
Hold at location address (FedEx location where your Customer will pick up their delivery)
If you are not currently using the hold at FedEx Location option, you are most likely providing only two (2) addresses (Shipping
and Billing/Recipient) in your current integration with FedEx systems.
Failure to accurately and appropriately integrate a HAL address into your existing FedEx shipment creation workflow can result
in costly shipment errors and delays and misunderstandings about shipment delivery status.
If you need help incorporating HAL locations outputted by the HAL Widget into your specific FedEx shipment creation workflow,
please contact the HAL development team (see contact information in Appendix E).
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 10 of 16
APPENDIX A
HAL JSON OUTPUT FORMAT
The structure and definition for the FedExHALWidget.HAL_FORMAT.JSON format is as follows:
{“SpecialServicesRequested”: { “SpecialServiceTypes”:
“HOLD_AT_LOCATION”, “HoldAtLocationDetail”: {
“PhoneNumber”: “”,
“LocationContactAndAddress”: { “Contact”: {
“PhoneNumber”: 9722630042,
“EMailAddress”: “[email protected]”
},
“Address”: {
“StreetLines”: “841 Macarthur Park”, “City”:
“Irving”, “StateOrProvinceCode”: “TX”,
“PostalCode”: 75063, “CountryCode”: “US”
}
},
“LocationType”: “FEDEX_OFFICE”
}
}}
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 11 of 16
APPENDIX B
HAL XML OUTPUT FORMAT
The structure and definition for the FedExHALWidget.HAL_FORMAT.XML format is as follows:
<SpecialServicesRequested>
<SpecialServiceTypes>HOLD_AT_LOCATION</SpecialServiceTypes>
<HoldAtLocationDetail>
<PhoneNumber></PhoneNumber>
<LocationContactAndAddress>
<Contact>
<PhoneNumber>9722630042</PhoneNumber>
<EmailAddress>[email protected]</EMailAddress>
</Contact>
<Address>
<StreetLines>841 Macarthur Park</StreetLines>
<City>Irving</City>
<StateOrProvinceCode>TX</StateOrProvinceCode>
<PostalCode>75063</PostalCode>
<CountryCode>US</CountryCode>
</Address>
</LocationContactAndAddress>
<LocationType>FEDEX_OFFICE</LocationType>
</HoldAtLocationDetail>
</SpecialServicesRequested>
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 12 of 16
APPENDIX C
SAMPLE WEB PAGE HAL INTEGRATION
Below is an abbreviated sample web page integration.
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<script
src="https://code.jquery.com/jquery-1.11.3.js"></script>
<link rel="stylesheet" href="../hal/hal-1.0.0.css">
<script src="../hal/hal-1.0.0.js"></script>
<script>
$(function() {
showShippingsOption(SHIPPING_OPTION.none);
$('#hpShippingOption input').on('change', function() {
var selectedShippingOption =
$('input[name=shippingOption]:checked').val();
if (selectedShippingOption === SHIPPING_OPTION.deliverToMyAddress) {
showShippingsOption(SHIPPING_OPTION.deliverToMyAddress);
} else if (selectedShippingOption === SHIPPING_OPTION.holdItForMe) {
showShippingsOption(SHIPPING_OPTION.holdItForMe);
}
});
var FedExHALWidget = null;
$('#hpSearch').on('click', function() {
if (!FedExHALWidget) { // avoid multiple instantiation
var halParams = {
searchRadiusOptions: [5, 10, 20],
defaultSearchRadiusOption: 10,
title: "Select a FedEx Hold-at-Location for Free",
resultsRequested: 30
};
FedExHALWidget = fedex.hal.FedExHALWidget();
FedExHALWidget.setParameters(halParams);
}
var userAddress = {streetLine1: $("#hpHalAddressLine1").val(), city:
$("#hpHalCity").val(),
stateOrProvinceCode:
$("#hpHalState").val(), postalCode: $("#hpHalZip").val()};
FedExHALWidget.findLocations(userAddress);
});
$('#hpNext').on('click', function() {
var selectedShippingOption =
$('input[name=shippingOption]:checked').val();
if (selectedShippingOption === SHIPPING_OPTION.holdItForMe) {
if (!FedExHALWidget) {
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 13 of 16
alert("Please, select a Hold-at-Location");
return;
}
var selectedHAL =
FedExHALWidget.getSelectedHAL(FedExHALWidget.HAL_FORMAT.XML);
if (!selectedHAL) {
alert("Please, select a Hold-at-Location");
} else {
var xmlSelectedHAL = selectedHAL.replace(/</g,
"&lt;").replace(/>/g, "&gt;");
selectedHAL =
FedExHALWidget.getSelectedHAL(FedExHALWidget.HAL_FORMAT.JSON);
var jsonSelectedHAL = JSON.stringify(selectedHAL);
var jsonSelectedHAL = selectedHAL;
$('#hpSelectedHAL').html("JSON: " + jsonSelectedHAL +
"<br/><br/> XML:" + xmlSelectedHAL);
$('#hpHALSelection').show();
}
}
});
$('#hpSelectedHALClear').on('click', function() {
$('#hpSelectedHAL').html("");
$('#hpHALSelection').hide();
});
});
$('#hpShowSelectedHAL').on('click', function() {
var selectedHAL = FedExHALWidget.getSelectedHAL();
if (selectedHAL) {
$('#hpSelectedHAL').html(JSON.stringify(selectedHAL));
} else {
$('#hpSelectedHAL').html("No HAL selected");
}
});
…
</script>
<title>HAL Integration</title>
</head>
<body>
<form id="hpShippingOption">
…
<div id="FedExHALWidget">
</div>
…
</form>
</body>
</html>
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 14 of 16
APPENDIX D
HAL WIDGET URLS
There are several types of JavaScript and CSS widget files. The URLs to retrieve these files are not listed in the Implementation
Guide, but rather, are set forth in the tables below:
File Type
JavaScript
Environment
Test
Version
1.0.0
File URL
https://wwwtest.fedex.com/templates/components/apps/HAL/hal/HALW-1.0.0-min.js
File Type
JavaScript
Environment
Production
Version
1.0.0
File URL
https://www.fedex.com/templates/components/apps/HAL/hal/HALW-1.0.0-min.js
File Type
CSS
Environment
Test
Version
1.0.0
File URL
https://wwwtest.fedex.com/templates/components/apps/HAL/hal/hal-1.0.0.css
File Type
CSS
Environment
Production
Version
1.0.0
File URL
https://www.fedex.com/templates/components/apps/HAL/hal/hal-1.0.0.css
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 15 of 16
APPENDIX E
CONTACT INFORMATION AND SUPPORT LEVEL
FedEx will provide needed support to your development team, not your online customers. The contact information
provided below is only for developer support and should not be shared with or provided to your online customers.
The FedEx development team that maintains the HAL Shopping Cart Widget may be reached by email at:
[email protected].
FedEx will work diligently to provide prompt responses to support requests relating to the HAL Widget.
FedEx HAL Implementation Guide
Version 1 / November 2016
Page 16 of 16