Works with ShopWired

WWSW guides should normally conform to one of the following types:

Where only theme changes are required, and a single piece of code needs to be added to the theme or within the ShopWired account
Where only theme changes are required, but more 'custom code' needs to be added to the theme
Where theme changes are required in conjunction with other integration work
Where only integration work is required, e.g.
- Webhooks
- XML feeds
- Make.com / Zapier scenarios

Style rules

All WWSW guides should follow:

ShopWired's style guide
ShopWired's markdown style guide
ShopWired's glossary
The rules in this WWSW style guide

WWSW help guides are informative, neutral and specifically for providing a set of instructions on how the platform can be used on ShopWired, the functionality that the WWSW provides and any key recommendations.

WWSW help guides should not be written as advertisements for third party platforms and should not use "selling" adjectives to describe the services of functionality that the platform provides (e.g. quick, easy, cheap). This type of information and writing style (according to the app page style guide) can be used on the platforms WWSW app listing page instead.

Help guide format

WWSW guides should typically have the following layout and format:

A brief introduction about the type of functionality that the platform provides (on paragraph perhaps with bullet points)
- Include a link to the app page in the help guide so the user can view more information about the platform
A section on how to create the account on the platform, including ShopWired's referral link
Any pre-requisites required to complete the integration (for example, if an integration uses Make.com then a statement that a make.com account is required combined with a referral link)

A support statement in the following format:

HINT: ShopWired can only provide support to you on the instructions provided in this help guide, for assistance with your {{ platform }} account contact {{ platform }} support directly.

If a general theme installation is required a !## section detailing how to add the theme code
Various sections, each listed as an !## tag detailing how to connect each piece of functionality

Mandatory section list

Required sections that must be included in every guide:

Introduction
Include the support statement
Account creation
Prerequisites (if applicable)
Theme installation (if applicable)
Functionality sections (!## per feature)
Recommendations (optional and only where meaningful)

General rules

General theme code installation

Where general theme code installation is required (i.e. a piece of code is added to every page on the theme) the recommended wording is:

Once you've created your {{ platform }} account, {{ platform }} will provide you with some code that needs to be added to your ShopWired website, similar to the example shown below:
'''<script id='pixel-script-poptin' src='https://cdn.popt.in/pixel.js?id=6a041d2223gh7' async='true'></script>'''
Add this code to your theme's `master.twig` file (so that it is displayed on every page of your website) by navigating to **[Website > Themes](https://admin.myshopwired.uk/themes/installed)!** and selecting the `code editor`! option for the theme that you'd like to install it on.
Add the code just above the closing `</head>` tag.

Platforms that add a section to a website page

Where a platform provides functionality to embed something on a website page (for example a contact form) recommend adding the code either as a custom HTML section to a landing page (or other page) or using the Tick here to enter additional custom HTML/JS/CSS setting for website pages.

To display {{ platform }} forms on your ShopWired website, once you've configured the form you'll be provided with embedding code for the form, similar to the example shown below:
'''<div class="poptin-embedded" data-id="96e896d952120"></div>'''
1. Navigate to **[Website > Themes](https://admin.myshopwired.uk/themes/installed)!**
2. Select `customise your theme` for the theme you'd like to install it on
3. Select `add a new section`
4. Select the `custom HTML` section type
5. Paste the embedding code into the **Custom HTML** setting
6. Select out of the section and use the theme editor to position the form on the page
HINT: Use ShopWired's [landing pages](/manual/website-pages/landing-pages) feature to add the form to a custom page on your website.
If you want to add the form to a [website page](/manual/website-pages/website-pages) select the **Tick here to enter additional custom HTML/JS/CSS setting** to add the code. 

Product feeds

Where a platform accepts an XML feed in Google Shopping's format, the help guide should recommend using ShopWired's product multi-channel feed.

To provide {{ platform }} with your product data:
1. Install the [Product multi-channel feed](https://admin.myshopwired.uk/apps/5)!** app
2. [Obtain the URL for your product feed](/manual/product-apps/product-multi-channel-feed#article-obtaining-your-xml-feed-or-xml-file) from your ShopWired account
- ShopWired recommends using the `Only published products`! feed
3. Enter this URL into your Smartsupp account into the {{ platform setting name }} setting

Alternatively, if the platform requires an XML feed in a specific format (and doesn't accept Google Shopping's format), the help guide should recommend using ShopWired's product XML feed feature.

Install the [Product XML feed]()!** app 
Add the code provided below to the **...** setting
Click save changes and ... to regenerate the feed
Obtain the URL for your product feed ...

Webhooks

Where a platform accepts data through a webhook, the help guide should recommend using ShopWired's webhook's feature in the following format.

Navigate to your ShopWired account and to **[Your account (top right) > API & webhooks](https://admin.myshopwired.uk/business/api-webhooks)!**
Navigate to the **Webhooks** section and select `Create webhook`!
Select the **Webhook topic** as `order.finalized` and enter the webhook URL into the **Enter the notification URL for the webhook** setting

All webhook domain names must be added to ShopWired superadmin as Whitelisted domains or subdomains so that the user/platform does not need to coplete webhook verification.

It may often be necessary to advise the user that they must complete an action within their ShopWired account or on their ShopWired website in order to trigger a webhook notification to be sent to the platform and, as a result, for test data to appear for mapping within the third party platform account.

When doing so, you must ensure that the help guide advises the user to complete this multi-part process in the following order:

Obtain the URL of the webhook from the platform
Add the webhook URL to their ShopWired account
If necessary, setup the webhook within the platform to be in "listening mode" (or similar)
Complete the action required on their website or within their ShopWired account that causes ShopWired to send the webhook notification
Await the platform to receive the webhook data
Complete the mapping

Many platforms will allow users to enter a test webhook payload into the platform for manual mapping, i.e. where it is not necessary for the platform to receive the webhook in 'real time'. The WWSW help guide should provide sample webhook data in a similar format to the below so that the user can copy and paste this into the platform.

{
  "event": {
    "topic": "order.finalized",
    "data": {
      "object": {
        "id": 123
        },
        "created": "order.date",
        "products": [
          {
            "id": "product.id",
            "sku": "product.sku",
            "url": "product.url",
            "title": "product.title",
            "imageUrl": "product.imageUrl"
          }
        ],
        "billingAddress": {
          "city": "billing.city",
          "name": "billing.name",
          "country": "billing.country",
          "emailAddress": "billing.email"
        }
      }
    }
}

In addition, we should provide a table showing the platform fields and how they are mapped to the ShopWired webhook data, e.g.

{ platform } data mapping field	ShopWired webhook data
Field 1 name	ShopWired webhook property 1 name
...	...

Make.com scenarios

Each scenario must be created inside the ShopWired Make.com account and published using Make.com's “Share blueprint” / public URL feature
The help guide must provide the official scenario URL for the user to open and import directly
A short description must explain what the scenario does, what triggers it, and which platform modules it uses
Writers must list all required user inputs (API keys, URLs, tokens) and include a table explaining each placeholder used inside the scenario
All modules inside the scenario must have clear names (e.g. “Send order to {{ platform }}”) rather than default labels
The scenario URL must include a version number (e.g. v1, v1.1). If the scenario changes, publish a new version and update the link
Users must be given a standard import-and-test sequence:
Select the scenario URL
Open it in Make.com
Create the scenario from the blueprint
Replace placeholder values
Connect the required modules
Turn the scenario on
Trigger the relevant event in ShopWired to test it
If the scenario uses a ShopWired webhook trigger, include a simplified sample payload and a table mapping the fields
Writers must state whether the scenario uses only HTTP modules or requires Make.com app modules (and if any require a paid plan)
Scenarios must remain minimal (no unnecessary routers, branches or advanced functions)
ShopWired can only support the scenario as provided; customised versions fall under Make.com support

Recommendations section

For some platforms, it is advisable for ShopWired to provide a recommendations section as a !## section so that we can advise our users on best practices to use the third party platform in conjunction with ShopWired.

Use ### tags for each specific recommendation where approximately one paragraph is required
Use - tags for bullet point recommendations where each recommendation is short (for example a single sentence)
Do not mix and match recommendations between ### and - - select one type only for the whole of the recommendations section