This feature is available from Shopware 6 Module Release Version 1.4.0
Rationale #
Our plugin automatically integrates itself onto the default pages that contain relevant data. However, there may be instances where a form developed by a third party doesn’t utilize the default templates. As a result, the plugin wouldn’t recognize their existence. To address this issue and facilitate the use of the plugin’s features on these pages, we’ve introduced the concept of a service marker.
A service marker is a specific, invisible HTML element that can be inserted on any page. It carries the necessary information to initiate Endereco services correctly and to bind them to the corresponding input fields.
In addition to the service marker, we also provide a Shopware 6 service component that offers a ready-to-use implementation of “doAccounting”. This component is crucial for session-based accounting of Endereco API usage.
There’s also a setting that allows you to specify which controllers the JS-SDK (JavaScript Bundle) should load. This feature enables third-party plugin developers to whitelist their implementation, secure the JS-SDK, and then use the service markers to connect Endereco services with the input fields.
Lastly, the developers can use the “doAccounting” function from the Shopware 6 service to finalize the implementation. This step ensures compatibility with the Endereco API accounting system, tying everything together seamlessly. This comprehensive approach empowers developers to integrate our plugin smoothly, regardless of their chosen form templates.
How it works #
The toolkit comprises three tools:
- Data Marker
- EnderecoService (Shopware 6 Service)
- JS-SDK Bundle (and the config script in the header area of the page)
To use the Data Marker, you need to have the capability to modify the template files of your extension. The JS-SDK Bundle is made available through the endereco.min.js file. This file is loaded on every page, provided that the page controller is whitelisted. However, it will be loaded on every page if the whitelist is deactivated in the plugin settings. By using these tools, it’s possible to connect a form to one of the plugin services and see tangible results.
It’s crucial to implement proper session closing. To assist with this, the plugin offers a service object that can be integrated via dependency injection. This service object processes $_POST data, identifies closable session IDs, and sends the so-called “doAccounting” to the Endereco API. The “doAccounting” process is a mechanism of the session-based billing system, which is standard for Shopware 6 plugins.
Whitelisting the controller #
The first step is to ensure that the JS-SDK bundle loads on the relevant page. To achieve this, we’ve developed a specific setting that lets you define the pages on which the JS-SDK should load, aside from the default ones.
The result of this setting, if done correctly, is that “endereco.min.js” is loaded on the relevant page, and a bunch of configuration and utility JavaScript is added to the header of the page.
Adding a data marker #
After the endereco.min.js is loaded and executed, it first loads the configuration and then initiates a scanner. This scanner scans the page for so-called Data Markers. These should be placed within the relevant form and contain information about which service should be connected to which input fields, and possibly some additional configuration information.
The next step involves connecting services from the JS-SDK with the corresponding input fields in the form. For this, you should utilize the Data Marker. Here’s an example:Finally, once the data has been verified and is ready to be persisted, a “doAccounting” request should be sent to the Endereco API. This action notifies the API that certain groups of requests, specifically the sessions, are now considered closed and, as a result, billable.
For instance, we connect the default Shopware address on the registration page to the service using this data marker:
<input
type="hidden"
name="endereco_data_marker" value="ams"
data-container-selector="form"
data-container-type="form"
data-form-handle-ajax-submit="true"
data-used-prefix="{{ prefix }}"
data-has-object="no"
data-name=""
data-type=""
data-country-code-selector="[name='{{ prefix }}[countryId]']"
data-subdivision-code-selector="[name='{{ prefix }}[countryStateId]']"
data-postal-code-selector="[name='{{ prefix }}[zipcode]']"
data-locality-selector="[name='{{ prefix }}[city]']"
data-street-full-selector="[name='{{ prefix }}[street]']"
data-ams-status-selector="[name='{{ prefix }}[amsStatus]']"
data-ams-timestamp-selector="[name='{{ prefix }}[amsTimestamp]']"
data-ams-predictions-selector="[name='{{ prefix }}[amsPredictions]']"
data-street-selector="[name='{{ prefix }}[enderecoStreet]']"
data-house-number-selector="[name='{{ prefix }}[enderecoHousenumber]']"
data-address-type="{{ addressType }}"
>Closing sessions on submit #
By default, the Shopware 6 plugin implements session-based billing. This means that Endereco is not counting every individual request, but rather groups of requests, or in other words, a session. A session pertains to a logical unity of data. For instance, there should be a session for the billing address, another session for the shipping address (since it’s a separate address, even if the content is the same), a session for the email address, another session for the phone number, and so forth. A session can encompass requests from different services. For instance, when entering an address, autocomplete requests usually come first, followed by an address check request.
Once the user sends the data to the server, the session should be closed. To assist with this, Endereco provides a service object, EnderecoService, that can be integrated using Dependency Injection.
//service.xml
...
<argument type="service" id="Endereco\Shopware6Client\Service\EnderecoService"/>
...The Namespace might contain “Shopware6Client” or “Shopware6ClientStore”, depending where the plugin comes from.
This Service offers several methods that can be useful.
Let’s say the user has submitted the form to the plugin, and the submission is directed to a specific controller.
The logic below should be executed prior to any server-side validation that might be in place:
Find accountable session IDs:
// Assuming we have a POST request
$accountableSessionIds = $this->enderecoService->findAccountableSessionIds($_POST);Send doAccounting for each session. Both context and salesChannelId need to be provided:
// Assuming we have a POST request $this->enderecoService->sendDoAccountings($accountableSessionIds, $context, $salesChannelId);
That’s it.
Help with the integration #
Endereco is eager to assist with the integration. If you encounter any issues or have questions, please feel free to contact us at support@endereco.de.
Additionally, if you have suggestions on how to simplify or enhance the plugin’s integration functionality, we welcome your input and may implement these features in a timely manner.
