Developer docs

nopCommerce plugin

The DeploySeal widget plugin for nopCommerce renders the widget tag in the storefront <head> with the environment's key, a declared environment label, a build marker and its own installer stamp (data-ds-installer, from 1.3.0) — and nothing else. It does not change your pages, your checkout or your data; it exists so that the readiness report can prove which environment and which build your testers were on. It works on nopCommerce 4.60 through 4.90, behaves identically on each, and is open source under the MIT licence.

<script
  src="https://cdn.deployseal.com/ds-widget.js"
  data-ds-site-key="ls_••••••••••••••••••••••••••••••••••••"
  data-ds-environment="staging"
  data-ds-build="4.90.8+a1b2c3d"
  data-ds-installer="nopcommerce-plugin/1.3.0"
  async
></script>

Supported versions

nopCommerce plugins are compiled against one nopCommerce version, so there is one zip per version. Pick the one that matches the version shown in the footer of your administration area. Every zip contains the same settings, the same Configure page and emits the same tag; the only visible difference is that the default build marker carries that version's own number.

nopCommerce	Built against	Runtime	Zip	Download
4.60	4.60.6	.NET 7	DeploySeal.Nop.Widget-4.60.zip	Releases
4.70	4.70.5	.NET 8	DeploySeal.Nop.Widget-4.70.zip	Releases
4.80	4.80.9	.NET 9	DeploySeal.Nop.Widget-4.80.zip	Releases
4.90	4.90.8	.NET 9	DeploySeal.Nop.Widget-4.90.zip	Releases

The plugin will also be listed on the nopCommerce Marketplace once the first public release is out; until then the releases page is the one place to download from. Source, build scripts and the end-to-end test that drives a real nopCommerce in Docker are in the same repository.

Install

Download DeploySeal.Nop.Widget-<version>.zip for your nopCommerce version from the table above.
In the administration area open Configuration → Plugins → Local plugins and use Upload plugin or theme to upload the zip. If you deploy files by hand instead, unzip it so that /Plugins/Widgets.DeploySeal/plugin.json exists.
Find DeploySeal widget in the list, click Install, then Apply changes. nopCommerce restarts — that is normal and takes a few seconds.
Click Configure on the plugin row (or open Configuration → Widgets and configure it there — make sure it is marked active on that page too).

Configure

The Configure page has three parts: the four steps below, a What this store will send panel, and the settings form. Follow the steps once per store.

In DeploySeal, open your site and create an environment for this store (for example Staging or Production).
Copy the environment's public key (it starts with ls_) into the Site key box. Use one key per environment per store, never one key for everything.
In that environment, register the exact origins listed under Origins to register. Matching is exact: scheme, host and port must all agree.
Tick Enabled, click Save, then open the storefront once and confirm the environment shows as Live in DeploySeal.

Settings

Setting	What it does
Enableddefault: off	The master switch: nothing is rendered on the storefront while it is off.
Site keydefault: empty	The public key of the DeploySeal environment this store is (ls_…; older ds_ keys still work) — not a secret, because it only works from the environment's registered origins.
Environment labeldefault: guessed from the store URL	The label this store declares itself as (lower-case letters, digits and hyphens, up to 32 characters); it is a declaration, not an identifier, and left empty it falls back to the guess — staging when the host contains staging, uat, test, dev, qa, sandbox, preprod or localhost, otherwise production.
Build marker sourcedefault: nopCommerce version + git SHA when available	Where the “which code is running” marker comes from, one of four options: nopCommerce version (4.90.8); nopCommerce version + git SHA when available (4.90.8+a1b2c3d, falling back to the version alone when no SHA can be read); Git SHA only (emits nothing when the file cannot be read); or Manual (the value typed below).
Git SHA file pathdefault: empty	A file holding the deployed commit SHA (7–40 hex characters on its first line) that your deploy pipeline writes; relative paths resolve from the application root, and App_Data/build-sha.txt is a good place.
Manual build markerdefault: empty	Used only when the source is Manual: one token, no spaces, up to 64 characters, changed by hand on every deployment.
Script host (advanced)default: https://cdn.deployseal.com	The origin the widget loader is fetched from — the only supported host, so leave it as it is.
Also load in the admin areadefault: off	Renders the tag inside /Admin as well, for the rare case where testers need to pin issues in the administration area; the admin layout has no head zone, so the tag goes into the first admin body zone instead.

Multi-store

Every setting can be overridden per store. Pick a store in the scope selector at the top of the Configure page, tick the override box beside a setting, and the value you save applies to that store only; stores without an override use the value from All stores. Because a DeploySeal environment is one origin list and one key, a nopCommerce installation with three stores wants three environments and three overridden Site key values — one key per environment per store. The Origins to register table marks which store is currently in scope so the two can be compared by eye.

What this store will send

This panel is the plugin's statement of fact: what it will emit for the store in scope, computed from the settings as saved. Compare it with the environment in DeploySeal before you rely on either.

Origins to register — every origin the store answers on, derived from its URL, its SSL setting and its HTTP_HOST list under Configuration → Stores. Register each one exactly as printed. If shoppers reach the store on another scheme, host or port that nopCommerce does not know about, register that too.
Declared environment label — the label the tag will carry, and beneath it the value guessed from the store URL, so you can see whether your explicit setting or the guess is in force.
Build marker emitted right now — the exact marker, its source, and (when a SHA file is configured) the resolved path with found and readable or missing or not a valid SHA. This is the value to copy verbatim into the campaign's release identifier. An amber notice appears when no SHA could be read.
Versions — the running nopCommerce version and the plugin version.
Tag that will be rendered — the script tag byte for byte, with a note when the plugin is not yet enabled, so what you see here is what a view-source on the storefront will show.

Build marker

The build marker answers which code was under test. The readiness report compares the campaign's declared release identifier with the markers observed while testers were on the store: confirmed when one observed marker equals the identifier (case-insensitively) or one is a prefix of the other and the shorter is at least 7 characters — so a short SHA confirms a full one; mismatch when markers were seen and none match; unverified when an identifier was declared but no marker was ever seen. Two or more distinct markers in one campaign raise an amber testing spans N deployments flag.

Prefer the commit. Have your deploy pipeline write the commit SHA into a file and point Git SHA file path at it. With the default source the marker becomes 4.90.8+a1b2c3d; with Git SHA only it is the SHA alone, and a campaign can then declare either the short or the full SHA.
Otherwise the version. Without a readable SHA the default degrades to 4.90.8, which is honest but does not change between deployments of the same nopCommerce version — so two deploys a week apart look the same to the report.
Copy it verbatim. Prefix rules run from the start of the string, so a1b2c3d will not confirm 4.90.8+a1b2c3d. Declare in the review exactly what the Configure page shows under Build marker emitted right now.
One token, no whitespace, at most 64 characters, stable for the life of a deployment and different on every deployment. The marker is resolved once per request from the saved settings; the time the page rendered is never a build marker.

The SHA file

# App_Data/build-sha.txt — written by your deploy pipeline, first line only
a1b2c3d4e5f60718293a4b5c6d7e8f9012345678

First line only, 7–40 hex characters; anything else counts as unreadable. Relative paths resolve from the application root. Write the file as part of the same deploy that copies the build, so the two can never drift.

Origins

Every widget request carries the browser's Origin header, and the API accepts it only if it exactly matches one of the environment's allowed origins: scheme://host[:port], compared case-insensitively after trimming one trailing slash. No wildcards, no subdomain matching, no port or scheme normalisation — https://staging.example.com, http://staging.example.com and https://staging.example.com:8443 are three different origins. That exactness is what makes the public key safe to ship in HTML.

An environment is its allowed-origins list — it has no hostname field. The plugin derives the store's origins for you and prints them under Origins to register; register them as printed rather than typing them from memory.
A store with SSL enabled produces https:// origins; a local Docker store on port 8090 produces http://localhost:8090. Both are correct for what they are, and neither matches the other.
Register one key per environment per store, never one key for everything: a campaign binds one environment, and the report infers one only when it has to.
In production an environment with no allowed origins rejects every widget call — the dashboard warns you until you add one.

Troubleshooting

The environment still says Not seen

Work through these in order. Origin mismatch — compare the origins under Origins to register with the environment's allowed-origins list character by character; scheme, host and port must all agree, and a store reached over both http and https needs both registered. Plugin not enabled — Enabled must be ticked on the Configure page and the widget must be active under Configuration → Widgets; the Configure page shows an amber notice when it is not. Key from the wrong environment — a key pasted from Production into a Staging store sends every heartbeat to Production; the site page then shows the mismatch warning below rather than a verified Staging. Only admin pages loaded — the tag is on the public storefront, not in /Admin; open a storefront page once, or turn on Also load in the admin area.

Amber label-mismatch warning on the site page

The label the store declared (Environment label, or the guess when it is empty) does not match the name of the environment the key belongs to. Either the key is in the wrong store, or the guess is wrong for a host that does not look like staging — set the label explicitly, or rename the environment. The evidence still lands where the key points; the warning exists precisely to catch a wrong mapping before a campaign relies on it.

No git SHA could be read

The Configure page shows the resolved path and whether the file was found and holds a valid SHA. The file must exist at deploy time, be readable by the application pool user, and carry 7–40 hex characters on its first line. Until it does, the default source degrades to the nopCommerce version alone, so the marker will not change between deployments of the same version and the report cannot tell one deploy from the next.

The tag appears twice in the page source

Another install path is also present — a pasted snippet in a theme layout, Configuration → Settings → General → Custom <head> HTML, or a tag manager. The tag whose loader executes configures the widget and the second mount is ignored, so nothing breaks — but the two can disagree about the label or the build marker, and the evidence goes to whichever ran. Because the plugin's tag carries data-ds-installer and a pasted snippet does not, the site page shows Two install paths are live on this environment when both are seen within a day. Remove the other one and let the plugin be the only source.

Inventory snapshot

Coming next

“Which plugins, at which versions, were installed when this was tested” is release evidence only a platform plugin can provide. A coming release will send DeploySeal a snapshot of the store's installed plugins — system name, display name, version and whether each is enabled — together with the nopCommerce version and the build marker in force, so the readiness report can print the inventory current at each campaign's testing window and diff it against the previous sealed version. The snapshot goes server to server, never from the browser, so it needs an organisation API key with the Write scope held as a secret on the Configure page. It is optional: the plugin works fully without one, and the inventory is an upgrade.

Ready to install? Create the environment and copy its key from the site page.

Open your sites

Not on nopCommerce? The widget reference covers the plain script tag, and the plugin obeys the same contract to the byte.