> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Campaign control

> Set up time-controlled marketing campaigns, bind configuration values and template areas to a campaign, and maintain schedules.

A campaign switches parts of your shop over for a defined period of time. Typical example: on two weekends a year you ship free of charge, and during that time a banner appears on the home page.

What makes this special is the division of labor. A campaign is set up once, by someone who knows their way around configuration and templates. Later, the merchant switches it on and off themselves, without anyone having to touch the configuration or templates.

![Kampagnen](https://mintcdn.com/websaleag-44ee7ea6/-4O6W3x8MU7HVGrG/images/kampagnen.jpg?fit=max\&auto=format\&n=-4O6W3x8MU7HVGrG\&q=85\&s=e6664d1c0086948e8b5c33d8134705af)

> [!NOTE]
>
> This function must be activated for your shop by WEBSALE AG.

## Services and tasks

| Service | Who works with it | Purpose |
| - | - | - |
| **Konfiguration**, **KampagnenManager** tab | whoever sets up the shop | Create campaigns and define which content they replace |
| **KampagnenSteuerung** | the merchant | Create, change and delete schedules |

Both services are located in the online service area.

## The building blocks of a campaign

| Building block | Purpose |
| - | - |
| Campaign ID | names the campaign. It appears in the configuration and templates |
| Config entry ID | names **one** place in the configuration that this campaign switches |
| Schedule | defines when the campaign is active. Multiple periods per campaign are possible |

> [!NOTE]
>
> The second level is the reason the system is so powerful. A "shipping cost reduction" campaign can switch UPS costs and DHL costs at the same time, with different values. To do so, it gets two config entries, for example `ups-versandkosten` and `dhl-versandkosten`.

> [!WARNING]
>
> Use meaningful IDs. They will later appear in the configuration and in the templates, and an ID like `Kampagne1` is worthless there. Write down both IDs when you create them; you will need them verbatim in the next steps.

## What you should know about campaigns

| Point | Rule |
| - | - |
| Scope | Campaigns are created for the whole shop and activated per subshop |
| Number | initially up to ten campaigns. The limit can be raised on request |
| Periods | any number per campaign |
| Time zone | configurable, so that the time zone of the respective region applies |
| Notice areas in templates | any number |
| Config entries | any number |

> [!WARNING]
>
> Campaign tags work in all editable subshop-specific configuration files, that is, in `.dat` and `.config` files of the respective subshop, for example also in `country.dat`. They do **not** work in global configuration files.

Guide: Configuration types

## The `WS-Campaign` tag in two roles

The same tag works differently in two places.

| Location | Notation | Effect |
| - | - | - |
| Configuration file | `$WS-Campaign(Kampagnen-ID,Config-Eintrag-ID)$` | is replaced by the stored content, depending on whether the campaign is active |
| Template | `{WS-Campaign(Kampagnen-ID)}…{/WS-Campaign(Kampagnen-ID)}` | section that only appears during the campaign |

> [!NOTE]
>
> In the configuration, there are **two** parameters and dollar signs as brackets; in the template, **one** parameter and the curly section brackets. If you mix up the notations, you do not get an error, you simply get no effect.

## Creating a campaign

The running example is a campaign `versandfrei` that changes the shipping costs of a shipping provider and displays a banner.

### Step 1: Prepare the affected configuration lines

In the **Konfiguration** service, open the shop configuration of the subshop in question and find the lines the campaign should change. Copy them into a separate editor window and create two versions: the previous values for the time without the campaign and the new values for the time with the campaign.

![Kampagne Konfigs Notierenall](https://mintcdn.com/websaleag-44ee7ea6/-4O6W3x8MU7HVGrG/images/kampagne_konfigs_notierenall.jpg?fit=max\&auto=format\&n=-4O6W3x8MU7HVGrG\&q=85\&s=9d16824a5bd25e2a9371d387a06ea876)

> [!NOTE]
>
> This preparation pays off because you can transfer both versions directly into the campaign config entry and you do not lose the original content.

### Step 2: Create the campaign

1. Switch to the **KampagnenManager** tab.
2. Move the mouse pointer over the **Kampagnen** title bar in the navigation area and click the document icon that appears.
3. In the dialog window, enter a name and campaign ID and define the basic settings.
4. Save. The campaign appears in the list in the navigation area.

![Kampagne1neuerstellung](https://mintcdn.com/websaleag-44ee7ea6/-4O6W3x8MU7HVGrG/images/kampagne1neuerstellung.jpg?fit=max\&auto=format\&n=-4O6W3x8MU7HVGrG\&q=85\&s=9ae1bcbe3a268f31718039bcbb46464b)

### Step 3: Create the config entries

Each place in the configuration that should be switched needs its own config entry.

1. Click the campaign in the list. Its definition appears on the right.
2. In the title row of the **Kampagnen-Config-Einträge** section, click the document icon.
3. Enter a name and config entry ID.
4. Under **Inhalt (aktiv)**, enter the version for the running campaign, and under **Inhalt (inaktiv)**, the version for the rest of the time. The inactive content is optional.
5. Save and create further entries as needed.

![Kampagne1konfig Eintrag](https://mintcdn.com/websaleag-44ee7ea6/-4O6W3x8MU7HVGrG/images/kampagne1konfig_eintrag.jpg?fit=max\&auto=format\&n=-4O6W3x8MU7HVGrG\&q=85\&s=d3f94775102fb8808c77ee8201da5637)

> [!NOTE]
>
> Related configuration lines, even an entire section, fit into a single config entry. So you do not need one entry per line, but one per place that is switched together.

### Step 4: Insert the tag into the configuration

Open the `shop.config` of each assigned subshop, find the content in question and replace it with the tag.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<+Deliverer>
   Allow                = yes
   ID                   = 1
   Name-Txt             = UPS
   BasicCost-List       = $WS-Campaign(versandfrei,ups-versandkosten)$   # ohne Kampagne: (0:10)(200:8)
   NoCost-Txt           = %%ShopConfigDeliverer01NoCostTxt%%
   DeliveryCountry-Rule = AllowCountries
   DeliveryCountry-List = DEU
</+Deliverer>
```

> [!WARNING]
>
> Write the original content as a comment on the same line. Otherwise, after the replacement only a tag remains there, and months later nobody can tell which value applied before. When you dismantle the campaign, you will need exactly this value again.

Then save and activate. While the view is still open, check whether the config entries were applied.

### Step 5: Create the area in the template

On every template you can set up an area that only appears during the campaign. This can be a sentence, a banner, a page section or a completely different page.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{WS-Campaign(versandfrei)}
   <img src="versandkostenbanner.jpg" alt="Dieses Wochenende versandkostenfrei bestellen">
{/WS-Campaign(versandfrei)}
```

> [!NOTE]
>
> The tag strictly requires a campaign ID as a parameter. Without a parameter, it returns nothing.

Reference: WS-Campaign()

## Defining and changing schedules

The campaign is now set up, but has no effect yet. Only a schedule switches it on.

1. In the online service area, select your shop ID and the **KampagnenSteuerung** service.
2. Select the campaign on the left. Its definition appears on the right.
3. In the title row of the **Zeitplan** section, click the document icon and choose a start and end date.
4. Save. The period appears in the list of schedules.

To change a schedule, click the pencil icon in its row; to delete it, click the trash can icon.

![Kampagnensteuerung](https://mintcdn.com/websaleag-44ee7ea6/-4O6W3x8MU7HVGrG/images/kampagnensteuerung.png?fit=max\&auto=format\&n=-4O6W3x8MU7HVGrG\&q=85\&s=8618e961f82c62faabe55a714d24c5e9)

> [!NOTE]
>
> Any user with the appropriate rights can maintain schedules. This is exactly why KampagnenSteuerung is a separate service: the merchant controls their own promotions without having to touch the configuration.

## Checking a campaign in advance

You can view a campaign before its schedule takes effect.

1. In the **Konfiguration** service, on the **Konfigurationen** tab, open the `shop.config` of the desired subshop.
2. Click the test configuration icon at the top right of the title row.
3. Select the campaigns to be tested, including several, and click **Testkonfiguration erstellen**.
4. Call up the shop in test mode with the additional parameter.

![Kampagne1 Test](https://mintcdn.com/websaleag-44ee7ea6/-4O6W3x8MU7HVGrG/images/kampagne1_test.jpg?fit=max\&auto=format\&n=-4O6W3x8MU7HVGrG\&q=85\&s=d70485bb348081a624ff793031189b86)

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.beispielshop.de/?test=on&campaign-test=on
https://www.beispielshop.de/?test=on&campaign-test=off
```

> [!WARNING]
>
> The campaign test mode only works together with the shop's test mode. `campaign-test=on` on its own does nothing.

> [!WARNING]
>
> In test mode, only **inactive** campaigns can be switched on. The reverse check, that is, switching off a running campaign for testing, is not possible this way. So plan the end of a promotion via the schedule and not via test mode.

> [!NOTE]
>
> Switching the campaign test mode on and off causes the shop to reload the configuration, once the test version and once the normal one. This is why the changed configuration values take effect immediately.

Guide: Switching the shop's test modes on/off

## Checking which campaigns are currently running

In the campaign list, there is a clock icon after each campaign. Green means the campaign is currently active according to its schedule; grayed out means inactive. You will find the list both in KampagnenSteuerung and in KampagnenManager.

> [!NOTE]
>
> The shop briefly caches the state of a campaign instead of determining it anew on every page request. A schedule change you have just made is therefore not reflected in the shop at the very same moment.

## Dismantling a campaign

> [!WARNING]
>
> Before you delete a campaign definition, reset the affected places in the configuration to their original state and remove the areas from the templates. A tag whose campaign no longer exists leaves a gap in the configuration where a value used to be, for example for shipping costs.

## Related topics

* Guide: Configuration types
* Guide: Switching the shop's test modes on/off
* Reference: WS-Campaign()


## Related topics

- [Special online services](https://dokumentation.websale.de/en/v8s/online-servicebereich/spezielle-online-dienste.md)
- [Wish list, comparison, upload and external services](https://dokumentation.websale.de/en/v8s/referenz/tags/ws/merkzettel-vergleich-upload-und-externe-dienste.md)
- [VAT](https://dokumentation.websale.de/en/v8s/preise/mehrwertsteuer.md)
- [Enabling and disabling shop test modes](https://dokumentation.websale.de/en/v8s/domains/testmodi-des-shops-ein-ausschalten.md)
- [Prices, taxes, and currency](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/shopkonfiguration-shop-config/preise-steuern-und-waehrung.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.