Script injectors

This article covers script injectors that you can use to add scripts to online pages in Microsoft Dynamics 365 Commerce.

The Dynamics 365 Commerce module library provides two prebuilt script injector modules: external script and inline script. Add these modules to a page or page template to inject inline or external scripts into the HTML head, body begin, or body end of a page as needed. For example, you can add a script for integration with partner analytics, or other service scripts.

External script module

The external script module enables you to add JavaScript from external sources by providing a URL that points to a valid JavaScript file. After you add the module by using Commerce site builder, add the script URL to the Script source property.

The external script module includes the execute script asynchronously and defer script execution configuration properties. The execute script asynchronously property specifies whether the script should be executed asynchronously. The defer script execution property specifies whether the script should be executed when the page finishes parsing configuration properties.

The following illustration shows an external script injector module being configured on a page template. The Script source property box is where you add the URL that points to the script source code that the module injects into the HTML for the rendered page.

Inline script module

The inline script module enables you to add inline JavaScript code directly to a page template or page. After you add the module by using Commerce site builder, paste the script into the Inline script property box, as highlighted in the following illustration.

Custom script injector modules

In some cases, you need to inject scripts into your site or site pages, but the prebuilt script injector modules from the module library aren't as flexible as you require. For example, you might want the authoring tools to expose extra configuration fields. In these cases, extend the prebuilt script injector modules into new custom script injector modules. You can add a custom script injector module to a page, a shared template, or a master template.

Create a custom script injector

To create a custom script injector, use the following command to create a new module.

C:\repos\MySite>yarn msdyn365 add-module my-script-injector

Next, open the my-script-injector.definition.json file and change the "$type" property to "scriptModule". After providing a friendly name and description, add the "Script" and "HTML head" categories, and "script" to the "tags" property. These categories and tags allow the script injector to access the applicable page slots already defined inside a page template.

Script modules contain a special "attributes" section that defines where the module can be placed. The attributes include "allowInBodyBegin", "allowInBodyEnd", and "allInHead", and the attribute values can be true or false. The default values for all three attributes are false, so it's important to specify where the module can be loaded.

You can also add configurations to allow the script to be added from within Commerce site builder.

The following example shows a configured custom script injector definition file.

{
    "$type": "scriptModule",
    "friendlyName": "My Script Injector",
    "name": "my-script-injector",
    "description": "Used to add custom script to a page.",
    "categories": [
        "Script",
        "HTML head"],
    "tags": ["script"],
    "attributes": {
        "allowInBodyBegin": true,
        "allowInBodyEnd": true,
        "allowInHead": true
    },
    "dataActions": {        
    },    
    "config": {
        "scriptSource": {
            "friendlyName": "Script source",
            "description": "The script source. Can be an external URL or a relative URL. Relative URLs are resolved from the public folder",
            "type": "string",
            "group": "script tag",
            "required": true
        },
        "async": {
            "friendlyName": "execute script asynchronously",
            "description": "specifies that the script is executed asynchronously",
            "type": "boolean",
            "default": false
        },
        "defer": {
            "friendlyName": "defer script execution",
            "description": "Specifies that the script is executed when the page has finished parsing",
            "type": "boolean",
            "default": false
        }
    }
}

Modify the script injector view file

You can modify the my-script-injector.tsx React file and the my-script-injector.view.tsx view file, if needed.

To create a custom script injector, use HtmlHeadInclude, which is a React Higher-Order Component that allows you to insert elements into the head of the page. It's simple to use, and you can add any elements you want in your view file between the <HtmlHeadInclude> tags, as shown in the following example.

import { HtmlHeadInclude } from '@msdyn365-commerce/core-internal';
import * as React from 'react';
import { IMyScriptInjectorViewProps } from './my-script-injector';

export default (props: IMyScriptInjectorViewProps) => {
    const scriptContents = `window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;ga('create', 'UA-XXXXX-Y', 'auto');ga('send', 'pageview')`;
    return (
        <HtmlHeadInclude>
            <script data-load-point='headStart' dangerouslySetInnerHTML={{ __html: scriptContents}} />
            <script data-load-point='headStart' async src={props.config.scriptSource} />
        </HtmlHeadInclude>
    );
};

The HtmlHeadInclude component can also be used to insert <title>, <meta>, <link>, and <style> tags into the head of an HTML document. Unlike scripts, these elements don't need a data-load-point attribute as they always are placed in the head.

After you deploy a custom script injector module to a Dynamics 365 Commerce environment, it appears in site builder.

Additional resources

Online channel extensibility overview