Was this helpful?

Alpaca Toolkit

The Alpaca Toolkit provides a method of integrating assets provided by Alpaca Travel. These assets include various prebuilt area guides, maps and itinerary layouts.

Example Inline Scripts

Using the below script examples, you can configure the behaviour and content using data attributes. The examples load an itinerary and an area guide into the alpaca-container div. You can style CSS for the presentation of the elements as appropriate for your site.

Example: Presenting an itinerary using a script tag

The below example will draw an itinerary onto the page of your site. The specific itinerary is configured by changing the data-id data attribute on the script tag. The data-view-mode attribute can configure the layout presentation that is used to present the asset. The data-container-id will configured  which div to replace the contents with the asset once it is ready. Finally, the data-inline data attribute will load the asset on page, allowing it to share the local storage access (opposed to using an iframe to seperate).

1<!-- Example of configuring script -->
2<div class="alpaca-wrapper alpaca-itinerary">
3  <div id="alpaca-container">
4    <!-- Recommended: Add you strategy here for the loading presentation -->
5    <span class="loading">Loading...</span>
6  </div>
7  <script
8    src="https://cdn.alpacamaps.com/scripts/alpaca-widget@v2.js"
9    data-id="journey/94d8276c-fd26-11ea-96fe-067ec0c7e8f4"
10    data-view-mode="article"
11    data-container-id="alpaca-container"
12    data-inline="true"
13  ></script>

Example: Presenting an area guide using a script tag

The below example places an area guide on the page, as defined by the data-id data attribute. It is configured to run inline, necessary to operate the asset on the same domain to share the local storage access. The content will load into the alpaca-container div once the application has downloaded and is ready to boot.

This example also passes through some query parameters, in order to filter the content to a specific state of the application.

1<!-- Example of configuring script -->
2<div class="alpaca-wrapper alpaca-area-guide">
3  <div id="alpaca-container">
4    <!-- Recommended: Add you strategy here for the loading presentation -->
5    <span class="loading">Loading...</span>
6  </div>
7  <script
8    src="https://cdn.alpacamaps.com/scripts/alpaca-widget@v2.js"
9    data-id="locale/wine-australia"
10    data-container-id="alpaca-container"
11    data-inline="true"
12    data-query-params="tags:prefilter=_appointment_only"
13  ></script>

Example: Advanced customisation of base URL's and API links

In certain circumstances, you may be advised to change the URL's that are being used for the toolkit to communicate with. These could be to do with changing the domain for custom domains, or changing API targets for preview releases.

1<!-- Example of configuring script with changing URL endpoints -->
2<div class="alpaca-wrapper alpaca-area-guide">
3  <div id="alpaca-container">
4    <!-- Recommended: Add you strategy here for the loading presentation -->
5    <span class="loading">Loading...</span>
6  </div>
7  <script lang="text/javascript">
8    // Modify the API URL for the content
9    var API_URL = 'https://embed.alpacamaps.com/api/v1'; // Default
10    // Modify the v2 API URL for the trip planning
11    var ALPACA_API_URL_V2 = 'https://withalpaca.com/api/v2'; // Default
12  </script>
13  <script
14    src="https://cdn.alpacamaps.com/scripts/alpaca-widget@v2.js"
15    data-id="locale/wine-australia"
16    data-container-id="alpaca-container"
17    data-inline="true"
18    data-base-url="https://made.withalpaca.com/"
19  ></script>

Shared Itinerary Creation

Assets can be enabled to provide itinerary planning features within the JavaScript application. You can integrate and share the itinerary planning features more broadly into the application via GraphQL.

  • You can leverage Itinerary GraphQL functions within your website application

  • You need to read/write to the local storage key detailed here in order to have the assets and your website application kept in sync

Example integrations

  • Full functioning Itinerary Creation, including simple lists and automatically routed itineraries

  • Create "Add to Itinerary" buttons on your website application that can determine whether a place is present within an itinerary

  • Show the number of places added to a users itinerary

  • Present a list of the places added to the itinerary

  • Add, remove and reorder places

  • Automatically create routes between an itinerary

Requirements You must be using the script tag with "inline=true" in order to leverage this feature. This is required due to the shared local storage, which is used to store the selected itinerary ID's.

Local Storage

Alpaca assets access the reference to the current itinerary being edited via the local storage key alpaca:add-to-itinerary:itinerary:ref:selected. The value of this must be in the format of alpaca://<itinerary-id>, such as:


You can listen to local storage events in order to obtain the reference to the itinerary as it is created.

  • Read the created itinerary from the localStorage key&#x20; alpaca:add-to-itinerary:itinerary:ref:selected on load to obtain any&#x20; itinerary that is in progress

  • Add an event handler to the window.localStorage so that if a new itinerary is started in the asset, you will also then have access to the ID

  • Push any newly created itineraries made outside the asset to local storage so that the asset also can use the itinerary.

Vanilla JavaScript

As an example gist, the below provides a basic javascript event handler for subscribing to the local storage to obtain the created itinerary.

1// Create a window variable in sync with the current itinerary
2var itineraryId = null;
4// Local storage key for accessing the current selected itinerary
5var localStorageKey = "alpaca:add-to-itinerary:itinerary:ref:selected";
6// Local storage key for accessing all the known itineraries (multiple list)
7var localStorageKeyList = "alpaca:add-to-itinerary:itinerary:refs:known";
10 * Obtain the current value of local storage for the selected itinerary
11 */
12function getLocalStorageItineraryId() {
13  // Access the current itinerary ref from the local storage
14  try {
15    // Update the local variable
16    var localStorageItineraryRef = window.localStorage.getItem(localStorageKey);
17    if (typeof localStorageItineraryRef === "string") {
18      return localStorageItineraryRef.replace("alpaca://", "");
19    }
20  } catch (err) {
21    // There is an issue accessing the window local storage (SecurityError)
22    console.warn(err);
23  }
24  return null;
28 * Set the local storage itinerary to a supplied itinerary ID
29 * @param {string|null} id ID of the itinerary to set into local storage
30 */
31function setLocalStorageItineraryId(id) {
32  try {
33    // Correct the ID to be a ref
34    var ref = (() => {
35      if (typeof id === "string") {
36        return "alpaca://" + id.replace("alpaca://", "");
37      }
38      return null;
39    })();
41    // Set the itinerary ID reference into local storage
42    window.localStorage.setItem(localStorageKey, ref);
43  } catch (e) {
44    // Error handling...
45    console.error(e);
46  }
49// Add an event listener to local storage to update our local variable
50window.addEventListener("storage", () => {
51  // When the local storage is updated, keep it in sync
52  var localStorageItineraryRef = getLocalStorageItineraryId();
53  if (localStorageItineraryRef !== itineraryId) {
54    itineraryId = localStorageItineraryRef;
55    // You can do something else with the updated itinerary ID here...
56    // callMyFunc(...)
57  }
60// Set the itinerary ID when we boot
61itineraryId = getLocalStorageItineraryId();

Custom Events

Alpaca also triggers custom events on the window that you can subscribe and observe. These are triggered by the application when certain events happen, and can bne an alternative to listening to the storage layer.

1// Create an event handler to listen to events from Alpaca
2function alpacaEventHandler(event) {
3  var method = event.detail.method;
5  console.log("Caught an event, such as createItinerary or deleteItinerary");
8// Register to the window as the event target
9window.addEventListener("alpaca", alpacaEventHandler);
Further References


Copyright © 2023 - Made with love ❤️ in Australia.