HTML analytics integration

HTML ads provide additional data points besides impressions and clicks. AppLovin enables you to track specific in-HTML events such as when HTMLs load, when users progress through challenges, when users complete experiences, and when users click call-to-action buttons.

When to use analytics

Integrate analytics into fully immersive HTML experiences. Do not integrate analytics into shorter HTML experiences such as:

• HTMLs with fewer than three interactions to complete
• HTMLs that redirect in less than five seconds from the first interaction

Implementation

Basic usage

Wrap all analytics calls in a safety check:

if (typeof window.ALPlayableAnalytics != 'undefined') {
  window.ALPlayableAnalytics.trackEvent('«event-name»');
}

Important notes

• Always wrap analytics calls: The safety check prevents errors when you test locally or serve ads on other networks.
• Do not define ALPlayableAnalytics: The SDK automatically defines the ALPlayableAnalytics object in its context.
• Only predefined events work: AppLovin does not track custom events.

Available events

Loading and display events

Event name	Description	Required	Deduped?	Report column
LOADING	In-playable loading starts. Implement this event if you perform loading or initialization before the user can interact, for example by showing a loading screen.	Optional	Yes	HTML loading
LOADED	In-playable loading completes.	Conditional1	Yes	HTML loaded
DISPLAYED	The HTML creative displays to the user and is ready for the user to interact with.	Required	Yes	HTML displayed

¹ If you implement the LOADING event you must implement this event. Otherwise, do not implement this event.

Challenge events

Event name	Description	Required	Deduped?	Report column
CHALLENGE_STARTED	The user begins a challenge in the HTML. Trigger this when the user clicks “start” or meaningfully interacts with the creative.	Optional	Yes	Challenge started
CHALLENGE_FAILED	The user fails a challenge by reaching a failure state.	Conditional1,2	Yes	Challenge failed
CHALLENGE_RETRY	The user retries a failed challenge.	Conditional1,2,3	Yes	Challenge retry
CHALLENGE_PASS_25	The user reaches 25% completion of a challenge.	Conditional1	Yes	Challenge pass 25
CHALLENGE_PASS_50	The user reaches 50% completion of a challenge.	Conditional1	Yes	Challenge pass 50
CHALLENGE_PASS_75	The user reaches 75% completion of a challenge.	Conditional1	Yes	Challenge pass 75
CHALLENGE_SOLVED	The user successfully completes a challenge.	Conditional1,2	Yes	Challenge solved

¹ Only implement these events if you implement the CHALLENGE_STARTED event.
² If you implement the CHALLENGE_STARTED event you must implement at least one of these events. If you do not implement the CHALLENGE_STARTED event, do not use these events.
³ Only implement this event if you implement the CHALLENGE_FAILED event, and only call it after the user fails the challenge.

Completion and conversion events

Event name	Description	Required	Deduped?	Report column
CTA_CLICKED	The user clicks the call-to-action button inside the creative.	Optional	Yes	CTA clicked
ENDCARD_SHOWN	The end card or summary screen inside the HTML experience is shown.	Optional	Yes	Endcard shown

Event order

Recommended sequence:

1. (Optional) LOADING
2. (Optional) LOADED
3. DISPLAYED
4. If challenge exists
   1. CHALLENGE_STARTED
   2. (Optional) CHALLENGE_PASS_25
   3. (Optional) CHALLENGE_PASS_50
   4. (Optional) CHALLENGE_PASS_75
   5. CHALLENGE_SOLVED
5. (Optional) ENDCARD_SHOWN
6. (Optional) CTA_CLICKED (can occur before or after ENDCARD_SHOWN depending on design)

Fail and retry sequence (example):

1. (Optional) LOADING
2. (Optional) LOADED
3. DISPLAYED
4. CHALLENGE_STARTED
5. (Optional) CHALLENGE_PASS_25
6. CHALLENGE_FAILED
7. CHALLENGE_RETRY
8. (Optional) CHALLENGE_PASS_25
9. (Optional) CHALLENGE_PASS_50
10. (Optional) CHALLENGE_PASS_75
11. CHALLENGE_SOLVED

Nuances

CTA visible from the start

• CTA_CLICKED can happen any time after DISPLAYED, not necessarily after ENDCARD_SHOWN.

Playables with no challenge (pure interactive demo, endcard-like HTML, no win or lose)

• Don’t use Playable Analytics.

Technical errors versus user failure

• Do not use CHALLENGE_FAILED for crashes, JS exceptions, load failures, or timeouts caused by technical issues.

No loading screen

• Skip LOADING and LOADED and start with DISPLAYED.

Endcard meaning

• ENDCARD_SHOWN refers to an endcard or summary screen inside the HTML playable experience, not the post-playable endcard template outside the playable.

Key metrics you can track

Performance metrics

• Load success rates (LOADING, LOADED)
• Display performance (DISPLAYED)

Engagement metrics

• Challenge engagement rates (CHALLENGE_STARTED)
• Challenge progression (CHALLENGE_PASS_25, CHALLENGE_PASS_50, CHALLENGE_PASS_75)
• Completion rates (COMPLETED, CHALLENGE_SOLVED)

Conversion metrics

• Call-to-action performance (CTA_CLICKED)
• End card effectiveness (ENDCARD_SHOWN)

Challenge performance

• Success versus failure rates (CHALLENGE_SOLVED versus CHALLENGE_FAILED)
• Retry behavior (CHALLENGE_RETRY)