Frequency Cap

Overview

The Frequency Cap card gives you precise control over how many times a user, or your entire audience, can interact with a template before a different experience is shown. Add the card from the Branches section in the Composer experience editor sidebar, then configure the scope, interaction mode, and limit that fit your goal.

Interaction Modes

The Interaction Mode drop-down in the Frequency Cap settings panel determines which user action increments the counter. The three available modes are: Visible impressions (each time the template becomes visible), Close clicks (each time a user dismisses the template), and Conversions (each completed purchase or checkout upgrade from a Show Offer card).

Visible impressions

A visible impression is registered when both of the following conditions are met: (1) at least 50% of the template’s pixels are loaded within the viewable area of the browser tab, and (2) those pixels remain in the viewable area for at least 1 continuous second. The viewable area is the visible screen space, excluding the browser address bar, dev tools panels, and menu bars.

Close clicks

A close click is registered when the user taps the template’s dismiss button. This applies to both modal and inline templates. For inline templates, you must add a close button to the template before close-click tracking can begin.

Conversions

The Conversions mode counts completed subscription purchases or checkout upgrades from a Show Offer card. The counter increments when a user finishes checkout, regardless of which specific term or upgrade option they selected. Counted conversion types include purchase offers and upgrade or downgrade offers.

Cap scope: per-user vs. global

Before choosing an interaction mode, select the scope of the counter.

Per-user cap

Each end-user has their own independent counter. Use this when you want to limit how many times one person can interact with a template before seeing a different experience. Interaction data is stored in the _pcfe browser cookie.

Global (audience-wide) cap

A single shared counter accumulates interactions from all users combined. Every qualifying interaction by any visitor increments the same counter. Enabling the Global (audience-wide) toggle in the settings panel switches the cap from per-user to global. Global caps support all interaction modes.

How to configure a frequency cap

1. In the Composer experience editor, drag the Frequency Cap card onto the canvas from the Branches section in the sidebar.

   

2. Placing the card opens the settings panel.

3. Choose the cap scope: Per-user (applies independently to each end-user) or Global (shared counter across all users).

4. Select an Interaction Mode: Visible impressions, Close clicks, or Conversions.

5. Enter the Max Interactions limit.

6. Set a time-frame to create a rolling cap. Per-user limits: up to 99 minutes or hours, 90 days, 12 weeks, or 3 months. Global limits: between 1 and 31 days.

7. Save the configured setup by clicking the checkbox in the top-right corner.

   

8. Linked to the card, you will now have two new branches available: Until cap is met and After cap is met.

   

9. In the Until cap is met branch, select the action card to display while the cap has not been reached.

   Primary Action: Choose the action that should be capped. The Frequency Cap card supports Show template, Show offer, and Show recommendation as primary actions. Click the placeholder in the ‘Until cap is met’ branch to select the primary action. You may also select any other actions to trigger along with the primary action. When the cap is met, these actions will also stop. Note that only actions may be added within the ‘Until cap is met’ branch; branches and events may not be added here.

   Cap-Dependent Action: Optionally, define an action to take once the cap is met. You can either select an action card from the left sidebar to fill in the placeholder in the "After cap is met" branch or use another frequency cap to define more cap-dependent actions. If you are capping an offer or template used as a paywall, be sure to add another to the "After cap is met" branch to limit an end-user's access to your content after they have reached the frequency cap with your initial action.

10. Optionally, configure the After cap is met branch to display a different action once the cap is reached.

11. Save and activate the experience.

Sharing a global counter across experiences

You can share the same audience-wide counter across multiple Composer experiences when using the Conversions interaction mode. The action card's Module ID is the key that links counters together. Action cards with the same Module ID increment the same counter, regardless of which experience triggers them.

1. In Experience 1, configure a global Frequency Cap and place the target action card in the Until cap is met branch.

2. Open the action card’s Dev Tools settings and copy the Module ID.

   
   

3. On the Frequency Cap card, open the drop-down menu and select Copy card and children.

   

4. In Experience 2, navigate to the location where you want to add the Frequency Cap, click the + icon, and select Paste card and children.

   

5. Open the pasted action card, select Dev Tools from the drop-down menu, and replace the newly generated Module ID with the Module ID copied from Experience 1.

   

Both Frequency Cap actions will now share the same Module ID and increment the same global counter across experiences.

How the frequency cap works

Rolling window

The interaction counter uses a rolling window. Each event is time-stamped, and the cap resets relative to when earlier events occurred—not at a fixed clock boundary.

Example: a user-level cap is set at 2 visible impressions per 1 hour.

• First impression at 15:27:01 — counter: 1.

• Second impression at 15:59:32 — counter: 2. Cap is now met.

Cap resets at 16:27:02 (one hour after the first impression). The primary action fires again.

• Third impression at 16:28:49 — counter: 1 (reset). Cap is met again at count 2.

Cap resets at 16:59:33 (one hour after the second impression).

Cookie tracking (user level)

Per-user caps use the _pcfe cookie to store interaction counts on the end-user’s browser. This cookie can store up to 30 interactions per type and expires after 90 days. If a user has not consented to cookie usage, impression and click tracking is suspended and the Frequency Cap card becomes inactive for that user.

For more information, see the Piano cookies documentation.

Use Cases

Impression-Based Content Rotation (Global Frequency Cap Use Case)

A media publisher wants to show a premium content unlock offer, but limit total audience exposure to 500 visible impressions per week. After 500 impressions have been served across all visitors, the offer is replaced by a different call-to-action until the weekly counter resets.

Limitations

The following constraints apply to the Frequency Cap feature:

• The Frequency Cap card is only available in site page view experiences.

• Per-user time-frame limits: up to 99 minutes or hours, 90 days, 12 weeks, or 3 months.

• Global time-frame limits: 1 to 31 days. Hard limits without a time-frame are not supported.

• Global interaction events are stored for a maximum of 31 days.

• The Conversions interaction mode requires a Show Offer card in the Until cap is met branch.

• Only actions may be added within the Until cap is met branch; branches and events cannot be added there.

• Failure to grant cookie consent suspends per-user impression and click tracking.

• Sharing a global counter across experiences is only supported for the Conversions interaction mode.

Last updated: July 02, 2026