Neostore SDK Add to Wallet Documentation

Introduction

The Neostore SDK Add to Wallet is designed to integrate seamlessly with your website, allowing users to add passes directly to their digital wallets. This SDK provides a JavaScript code example that can be embedded into your website to display the “Add to Wallet” button, which adapts dynamically based on the user’s device (iOS, Android, or desktop). This guide will walk you through the installation, configuration, and customization of the SDK.

Features

• Device Adaptation: Automatically displays the appropriate button based on the user’s device.
  • iOS Devices: Displays the “Add to Apple Wallet” button.
  • Android Devices: Displays the “Add to Google Wallet” button.
  • Desktop: Displays a pop-up with a QR code for downloading the pass to a mobile device.
• Design Compliance: Ensures compliance with Apple and Google’s design and implementation guidelines.
• Maintenance: Automatically updates to comply with the latest versions and requirements from Apple and Google.
• Security: Guarantee pass distribution integrity and security
• Internationalization: the SDK will automatically adjust based on the language preference of the user

Prerequisites

Before integrating the SDK, ensure the following:

1. Neostore Configuration: Neostore must be correctly configured with the appropriate templates for wallets
2. Data Source Connector: Ensure Neostore is connected to Secutix through the Secutix connector
3. Modification right to your website: The SDK integrates directly to your website, you’ll need access to modify or integrate custom source code.

Reminder

Neostore secutix integration uses secutix movementId identifier to uniquely identifies a wallet card.

Neostore SDK Add to Wallet Integration Examples

Script initialization

The first step is to integrate the SDK script within your website, you can use the following source code as an example :

<script type="text/javascript">
(function (n, e, o) {
    var s=n.createElement("script");
    s.src="https://sdk.neostore.cloud/scripts/"+e+"/cinto@1";
    s.async=1;
    s.onload=function(){neostore.cinto.initialize(e,o);n.body.appendChild(s);};
})(document, "<neostore tenantId>", { });
</script>

Replace <neostore tenantId>with your actual neostore tenant name.

The script can be added in the head or body of the html document

Button with single ticket

Here are detailed integration examples for different security scenarios using the Neostore SDK Add to Wallet.

1. Using movementId, fileId, contactId, and ticketId

This example shows how to display the “Add to Wallet” button when the website knows the movementId and the associated fileId, contactId, and ticketId related to this movement.

<div data-neostore-addToWalletButton
     data-neostore-externalIdentifiers-secutix.movementId-value="<movementId>"
     data-neostore-externalIdentifiers-secutix.movementId-secret="<fileId>|<contactId>|<ticketId>">
</div>

Replace the placeholders <movementId>, <fileId>, <contactId>, and <ticketId> with the actual values from Secutix.

2. Using HMAC Calculation

If you only know about secutix movementId, you can calculate an HMAC based on a neostore secret and the movementId from Secutix.

<div data-neostore-addToWalletButton
     data-neostore-externalIdentifiers-secutix.movementId-value="<movementId>"
     data-neostore-externalIdentifiers-secutix.movementId-hmac="<hmac_sha256(secret, movementId)>">
</div>

Replace <movementId> with the actual value from secutix, and <hmac_sha256(secret, movementId)> with the HMAC calculation using a standard hmac_sha256 function.

3. Basic Security Standard: Using movementId Only

If you don’t have the necessary information to calculate an HMAC, you can call the Neostore API directly with the movementId to retrieve the passId and then use this passId to retrieve the pass.

<div data-neostore-addToWalletButton
     data-neostore-passId="<passId>">
</div>

Replace <passId> with the actual passId retrieved from the Neostore API. See How to get passId

Notes

• Ensure the SDK URL and initialization code are correct and up-to-date based on Neostore’s latest SDK version.
• The hmac_sha256 calculation should be done server-side to ensure security.
• For the third scenario, you may need to set up a server-side API call to NeoStore to retrieve the passId based on the movementId.