Scroll Triggers and Ad Rotation

Scroll-Triggered Visibility

A scroll trigger determines when an advertisement should be visible based on the visitor's progress through a scrollable area.

Controls

Control	Description
Enable Scroll Trigger	Enable scroll-based visibility
Trigger Start (%)	Beginning of visibility range
Trigger End (%)	End of visibility range

Both percentage fields accept values from 0 to 100 in the interface.

How Scroll Progress Is Calculated

The generated script identifies a scrollable ancestor when possible.

If no suitable ancestor is found, it falls back to document-level scrolling.

Conceptually:

Scroll Progress (%) =
  Current Scroll Position
  ----------------------- × 100
  Maximum Scroll Distance

Example: Mid-Page Visibility

Configure:

Enable Scroll Trigger: Yes
Trigger Start: 25
Trigger End: 75

The advertisement is intended to appear when the scroll position is between 25% and 75% of the relevant scroll range.

Scroll Trigger Behavior

The generated script:

Identifies a scroll container.
Waits for the document layout to stabilize.
Calculates the current scroll percentage.
Sets advertisement visibility.
Recalculates on scrolling and window resizing.

Special Case: 0–0

When both values are zero, the generated script displays the advertisement without applying a restrictive percentage window.

Start: 0
End: 0

Important Implementation Detail

The generator defines an Enable Scroll Trigger option, but the generated visibility function primarily evaluates the start and end values.

The JavaScript variable corresponding to the enable checkbox is not used by that visibility function.

Consequently, nonzero trigger values may affect visibility even when the checkbox is disabled.

To avoid unexpected behavior, return both percentages to zero when scroll visibility is not desired.

Advertisement Rotation

OK Ads supports multiple advertisements associated with a common randomization group.

The system can choose which grouped advertisement appears and optionally rotate between them.

Controls

Control	Purpose
Rotate Ads	Enable automatic rotation
Rotation Interval (ms)	Delay between rotations
Randomization Group	Group identifier shared by related advertisements

Randomization Groups

To group advertisements, enter the same group name into each advertisement's Randomization Group field.

Example:

homepage-promotions

The generated advertisement receives a group class based on this name.

Conceptually:

ok-ad-group-homepage-promotions

Group Requirements

Grouped advertisements must be present within the same applicable document for the shared JavaScript to identify them.

The group system uses document-level element queries.

Advertisements embedded in separate iframe documents do not automatically share the same group state.

Randomized Initial Selection

Each generated advertisement obtains a random score using the Web Crypto API.

The script then compares available advertisements in its group and selects the one with the highest score.

The intention is to display a single selected advertisement at a time.

Automatic Rotation

Enable Rotate Ads to cycle through members of a group.

Example

Rotate Ads: Enabled
Rotation Interval: 30000
Randomization Group: homepage-promotions

This requests rotation approximately every 30,000 milliseconds, or 30 seconds.

Rotation Interval

Setting	Value
Initial form value	30,000 ms
Minimum enforced in JavaScript	3,000 ms
Maximum enforced in JavaScript	120,000 ms

Although the HTML input specifies a minimum of 1,000 milliseconds, the JavaScript clamps the generated interval to at least 3,000 milliseconds.

Examples

Milliseconds	Duration
3,000	3 seconds
10,000	10 seconds
30,000	30 seconds
60,000	1 minute
120,000	2 minutes

Closing Grouped Advertisements

When an advertisement has a close button and belongs to a group, the generated handler attempts to:

Mark the group closed.
Stop any active rotation timer.
Hide the advertisements in the group.

For an ungrouped advertisement, closing hides its individual container.

Important Grouping Limitations

Shared Global State

The generated script uses page-global objects to track closed groups and rotation timers.

In the supplied implementation, these objects are reset when each advertisement script initializes:

window.__okads_closed_groups = Object.create(null);
window.__okads_rotators = Object.create(null);

When several advertisement snippets are embedded together, these resets can interfere with the intended shared state.

The grouping and rotation behavior should therefore be tested carefully.

No Persistent Dismissal

The generated close action does not store dismissal state across browser sessions.

A closed advertisement may reappear after a page reload.

No Impression or Click Analytics

The supplied generator does not implement an advertising analytics dashboard or impression tracking system.

Its rotation logic concerns visibility and display selection.

Recommended Workflow

Create two or more advertisements.
Assign the same randomization group.
Enable rotation where required.
Choose the interval.
Copy each generated advertisement snippet.
Insert the snippets into the same webpage.
Test initial selection, rotation, and closing behavior.

Best Practices

Use unique group identifiers for unrelated placements.
Avoid extremely short rotation intervals.
Test multiple snippets together.
Verify that closed groups remain hidden during the current page session.
Check scroll-trigger interactions.
Avoid relying on rotation as a replacement for ad analytics.

Important: Group rotation is implemented as client-side display logic. It does not provide guaranteed equal delivery, persistent ad scheduling, or impression accounting.