Context Gateway

DANGER

Security and privacy

With the Context Gateway, Shopware allows your app to manipulate the customer context, which includes sensitive information like customer addresses, payment methods, and more. It is your responsibility to ensure that the commands are valid and do not compromise the security or privacy of customers.

Due to the powerful nature of this feature, it should only be used if your app server is properly secured and the commands it sends are fully trusted and validated.

Context

As of Shopware version 6.7.1.0, the Context Gateway has been introduced.

The Context Gateway is a powerful feature that enables apps to securely access and interact with the customer context — based on the current cart and sales channel — allowing for more informed decision-making on the app server. This enhancement empowers app developers to dynamically tailor the shopping experience by manipulating the customer context.

It serves as the bridge between your app’s JavaScript and your app server.

Prerequisites

You should be familiar with the concept of Apps, their registration flow as well as signing and verifying requests and responses between Shopware and the App backend server.

App base guide

Your app server must also be accessible to the Shopware server. You can use a tunneling service like ngrok for development.

Manifest configuration

To indicate to Shopware that your app uses the context gateway, you must provide a context property inside a gateways parent property of your app's manifest.xml.

Below, you can see an example definition of a working checkout gateway configuration.

manifest.xml

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <!-- ... -->

    <gateways>
        <!-- ... -->
        <context>https://my-app.server.com/context/gateway</context>
    </gateways>
</manifest>

After the successful installation of your app, the context gateway is ready to be called by Shopware.

Context Gateway Endpoint

To trigger the context gateway, your integration can call the additional Store API route: .
This endpoint will forward the request to your app server’s context gateway endpoint, which must be configured in your app's manifest.

To allow the shop to identify your app, the request must include the appName, which is defined in your app’s manifest.xml.

Your app server will receive the following payload:

• The request source, including:
  • The URL of the Shopware shop
  • The Shop ID
  • The app version
  • Any active in-app purchase.
• The current SalesChannelContext
• The current Cart
• Any custom data you include in the request body

INFO

Communication between Shopware and your app server is secured via the app signature verification mechanism, ensuring that only your app server can respond to context gateway requests.

Storefront Integration

To trigger the context gateway from the Storefront, use the endpoint. This route is automatically registered by Shopware.

You can include any custom data in the request body - Shopware will forward this data to your app server.

To simplify this integration, Shopware provides the ContextGatewayClient service. This JavaScript client is intended for use within your app and handles communication with the context gateway endpoint. It returns a response containing:

• A (new) context token
• An optional redirect URL

Here is an example JavaScript plugin that triggers the context gateway when a button is clicked in the Storefront:

context-gateway.js

import Plugin from 'src/plugin-system/plugin.class';
import ContextGatewayClient from 'src/service/context-gateway.service';

export default class MyPlugin extends Plugin {
  init() {
    this._registerEvents();
  }
  
  _registerEvents() {
    this.el.addEventListener('click', this._onClick.bind(this));
  }
  
  async _onClick() {
    // create client with your app name
    const gatewayClient = new ContextGatewayClient('myAppName');
    
    // call the gateway with optional custom data
    const tokenResponse = await gatewayClient.call({ some: 'data', someMore: 'data' });
    
    // either: you can work with the new token or redirect URL
    // this means you have to handle the navigation yourself, e.g. reloading the page or redirecting to the URL
    const token = tokenResponse.token;
    const redirectUrl = tokenResponse.redirectUrl;

    // or: if you want shopware to handle the navigation automatically, even supplying an optional custom target path is possible
    await gatewayClient.navigate(tokenResponse, '/custom/target/path');
  }
}

INFO

Navigation customTarget Behavior

The customTarget parameter allows you to optionally control the redirect path used by the navigate method.

• If customTarget is an absolute path (starts with /), it completely replaces the path portion of the redirectUrl.
  This can be used to override sales channel subpaths in the redirectUrl.
  Example: https://example.com/en → https://example.com/custom/target/path

• If customTarget is a relative path, it is appended to the existing path of the redirectUrl.

• If customTarget is null, the behavior depends on whether a redirectUrl is present:

  • If present: the redirectUrl is used as-is.
  • If not: the current page is reloaded to apply context changes.

Trailing slashes are automatically removed to ensure clean and consistent URLs.

App server response

WARNING

Connection timeouts

The Shopware shop will wait for a response for 5 seconds. Be sure that your context gateway implementation on your app server responds in time, otherwise Shopware will time out and drop the connection.

Your app server can respond with a list of commands to modify the current sales channel context.
These commands can be used to perform actions such as:

• Changing aspects of the customer context, like:
  • Changing the active currency
  • Changing the active language and more
• Registering a new customer
• Logging in an existing customer

You can find a complete reference of all available commands in the command reference.

For example, you might want to update the context to a different currency and language if the current currency is not GBP.

Command Validation

Shopware performs basic validation on the commands returned by your app server to ensure they are reasonable to execute.

The following checks are enforced:

• The command must be recognized as valid, e.g. . See the full list of available commands.
• The payload must be valid for the respective command type.
• Only one command per type is allowed. For example, you cannot include two commands in a single response.
• A maximum of one or command is allowed per response.

Event

Plugins can listen to the Shopware\Core\Framework\Gateway\Context\Command\Event\ContextGatewayCommandsCollectedEvent. This event is dispatched after all commands have been collected from the app server and allow plugins to modify or add commands based on the same payload the app received.

Special Considerations

• The context_login-customer command allows your app to log in a customer without requiring their password. Use this feature with caution to uphold the shop’s security and privacy standards.

• The context_register-customer command will create a new customer account and automatically log them in. Make sure to validate the provided data before issuing this command. See the RegisterCustomerCommand reference for the list of accepted fields.

In both cases, your app must ensure that the customer has explicitly consented to be registered or logged in.