Skip to main content

Connection

The Storefront API uses SignalR for real-time communication. This page explains how to establish and manage a connection from your frontend application.

CORS Whitelisting Required

Before connecting, ensure your domain has been whitelisted for CORS. See Domain Whitelisting for details.

SignalR Client Library​

Include the SignalR JavaScript client library in your application. You can use a CDN or install it via npm.

CDN​

<script src="https://cdnjs.cloudflare.com/ajax/libs/microsoft-signalr/6.0.1/signalr.min.js"></script>

npm​

npm install @microsoft/signalr

Establishing a Connection​

Create a connection to the SignalR hub using the HubConnectionBuilder:

const connection = new signalR.HubConnectionBuilder()
  .withUrl("https://papi.skchase.com/public/hub/storefront")
  .configureLogging(signalR.LogLevel.Information)
  .build();

Starting the Connection​

Start the connection before invoking any hub methods:

async function startConnection() {
  try {
    await connection.start();
    console.log("Connected to Storefront API");
  } catch (err) {
    console.error("Connection failed:", err);
  }
}

Registering Event Handlers​

Register event handlers before starting the connection to ensure you don't miss any events:

// Register handlers first
connection.on("BasketUpdated", (basket) => {
  console.log("Basket updated:", basket);
});

connection.on("SomethingHappened", (error) => {
  console.log("Error occurred:", error);
});

// Then start the connection
await connection.start();

Connection Lifecycle​

Automatic Reconnection​

SignalR supports automatic reconnection. Configure it when building the connection:

const connection = new signalR.HubConnectionBuilder()
  .withUrl("https://papi.skchase.com/public/hub/storefront")
  .withAutomaticReconnect()
  .build();

Handling Disconnection​

Monitor connection state changes to handle disconnections:

connection.onclose((error) => {
  console.log("Connection closed:", error);
});

connection.onreconnecting((error) => {
  console.log("Reconnecting:", error);
});

connection.onreconnected((connectionId) => {
  console.log("Reconnected with ID:", connectionId);
  // Resume shopping to restore basket state
});

Complete Connection Example​

class StorefrontConnection {
  constructor(hubUrl, salesChannelId) {
    this.hubUrl = hubUrl;
    this.salesChannelId = salesChannelId;
    this.connection = null;
  }

  async initialize() {
    this.connection = new signalR.HubConnectionBuilder()
      .withUrl(this.hubUrl)
      .withAutomaticReconnect()
      .configureLogging(signalR.LogLevel.Information)
      .build();

    // Register event handlers
    this.connection.on("BasketUpdated", this.onBasketUpdated.bind(this));
    this.connection.on("SomethingHappened", this.onError.bind(this));

    // Handle reconnection
    this.connection.onreconnected(async () => {
      await this.resumeSession();
    });

    // Start connection
    await this.connection.start();
  }

  onBasketUpdated(basket) {
    // Handle basket updates
  }

  onError(error) {
    // Handle errors
  }

  async resumeSession() {
    // Resume shopping session after reconnection
  }
}