From c99dff2952af004de1add0b19fc50b01e090ec16 Mon Sep 17 00:00:00 2001 From: Dennis Garding Date: Thu, 19 Oct 2023 17:00:28 +0200 Subject: [PATCH] NEXT-30678 - Add documentation for adding shipping methods via manifest.xml (#1140) * NEXT-30678 - Add documentation for adding shipping methods via manifest.xml * Add grammar and language changes --------- Co-authored-by: Micha Hobert --- guides/plugins/apps/shipping-methods.md | 302 ++++++++++++++++++++++++ 1 file changed, 302 insertions(+) create mode 100644 guides/plugins/apps/shipping-methods.md diff --git a/guides/plugins/apps/shipping-methods.md b/guides/plugins/apps/shipping-methods.md new file mode 100644 index 000000000..e9417f938 --- /dev/null +++ b/guides/plugins/apps/shipping-methods.md @@ -0,0 +1,302 @@ +--- +nav: + title: Shipping methods + position: 25 + +--- + +# Shipping methods + +Starting with version 6.5.7.0 as **experimental feature**. Shopware has introduced experimental functionality for adding shipping methods via the App Manifest to a shop. **The entire functionality and API are subject to change during the development process.** + +## 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. + + + +Your app server must be also accessible for the Shopware server. + +## Manifest configuration + +### Basic configuration +The following example represents the most minimal configuration for a shipping method. + +**Important!** + +Ensure that the `` of your shipping method remains unchanged, as Shopware will deactivate or delete shipping methods that do no longer appear in the manifest during app updates. +```xml +// manifest.xml + + + + + + NameOfYourShippingMethodApp + + + + + + + + NameOfYourFirstShippingMethod + First shipping method + + + + c8864e36a4d84bd4a16cc31b5953431b + From 2 to 4 days + 2 + 4 + day + + + + + +``` + +### Delivery Time +The app manufacturer should initially display the standard delivery time to the shop manager, who can subsequently adjust it as needed. The delivery time requires some configurations. + +#### Id +The ID should only be generated initially and should remain unchanged thereafter. Changing it will result in the creation of a new one. + +::: info +Please note that you should not modify the ID of the shipping time. +::: +#### Name +The name should describe the delivery time simply, briefly and comprehensibly. + +#### Min / Max +The min and max values depend on the unit. Assuming the unit is days, in our example, the delivery time has a range from 2 to 4 days. + +#### Unit +The following values are possible units +- hour +- day +- week +- month +- year + +```xml +// manifest.xml + + + + + ... + + + + + NameOfYourFirstShippingMethod + First shipping method + ... + + c8864e36a4d84bd4a16cc31b5953431b + From 2 to 4 days + 2 + 4 + day + + ... + + + + +``` + +### Extended configuration +The functionality offers more than one identifier name. The following examples represent all possible configurations. + +* Translation of fields that are visible to the customer and requires a translation +* Shipping method description +* Shipping method icon +* Shipping method active (expects true or false). Default value is `false` + +```xml +// manifest.xml + + + + + ... + + + + + + NameOfYourFirstShippingMethod + First shipping method + Erste Versandmethode + + c8864e36a4d84bd4a16cc31b5953431b + From 2 to 4 days + 2 + 4 + day + + + This is a simple description + Das ist eine einfache Beschreibung + icon.png + true + https://www.yourtrackingurl.com + 2 + + + + +``` +### Description +You can initially add a description for the customer. + +::: info +Please note that the manifest cannot modify the description once you install the app, as the merchant can change it. +::: +```xml +// manifest.xml + + + + + ... + + + + + NameOfYourFirstShippingMethod + First shipping method + ... + This is a simple description + Das ist eine einfache Beschreibung + C'est une description simple + ... + + + + +``` + +### Icon +You can initially add a shipping method icon. You must specify the path to this icon as relative to the manifest.xml file. For example, you have the following directory structure: +``` +- YourPluginDirectory + - assets + - icons + - yourIcon.png + - manifest.xml +``` +The path should be: `assets/icons/yourIcon.png` + +::: info +Please note that the manifest cannot modify the icon once you install the app, as the merchant can change it. +::: +```xml +// manifest.xml + + + + + ... + + + + + NameOfYourFirstShippingMethod + First shipping method + ... + assets/icons/yourIcon.png + ... + + + + +``` +### Active +You can activate the shipping method by default. Possible values for active are `true` or `false` + +- true: Activates the shipping method +- false: Deactivates the shipping method. Alternatively, you can leave out active + +```xml +// manifest.xml + + + + + ... + + + + + NameOfYourFirstShippingMethod + First shipping method + ... + true + ... + + + + +``` + +### Tracking url +It is possible to add a tracking URL for customers to monitor the delivery status. + +```xml +// manifest.xml + + + + + ... + + + + + NameOfYourFirstShippingMethod + First shipping method + ... + https://www.yourtrackingurl.com + ... + + + + +``` + +### Position +Here, you can set the display order of the shipping methods in the checkout. If you omit the tag, the position of the shipping method is 1 by default. + +```xml +// manifest.xml + + + + + ... + + + + + NameOfYourFirstShippingMethod + First shipping method + ... + 2 + ... + + + + +```