- Published
- Nov 4, 2026
- Reading time
- 11 min read
IMA HTML5 Custom Click Tracking: Eligibility and UI Checks
Debug an IMA HTML5 custom click element with current-ad eligibility, visibility, placement and lifecycle checks, then verify navigation and reporting.

In this guide (9 sections)
Passing a custom click element to IMA HTML5 does not make it an active ad button for every device and creative. Check isCustomClickTrackingUsed() for the current ad when STARTED fires, keep the element outside the video player, and manage its visibility in your application. If the SDK is not using it, do not force a click by opening destinations and replaying tracking URLs yourself.
The immediate question is whether this ad is using the supported custom-click path. Only after that should you investigate the actual interaction, navigation, recipient notifications and report. A visible button, a local DOM click and a platform-reported ad click are different observations.
This guide addresses that HTML5 SDK integration task. For unexpected television, remote, QR or companion totals, use the separate CTV interaction measurement checklist.
The real questions have two different failure branches#
An August 2018 support question asks why a supplied custom element does not open the destination or trigger click tracking. Support identifies a false runtime custom-click result. A December 2018 question reports a true result but confusing pause/resume and click behavior. Its public reply requests more reproduction evidence; the opened thread does not establish a completed fix.
A separate August 2023 question asks for a custom button below the video on all devices. These are older evergreen questions, not evidence of a current SDK outage. They establish a repeated implementation need: distinguish supported current-ad behavior from a requested universal UI feature.
Use current API documentation to define the integration. Old device examples, debug logs and support suggestions should not become a present-day compatibility matrix or a claim that the same historical bug still exists.
Check click-element eligibility for the ad
Record SDK eligibility, element placement and visibility through the ad lifecycle.
Use the tracking QA checklistOpens a practical guide. No email required.
Check eligibility on the current ad#
The current AdsManager reference says custom click tracking is used only when a custom element is supplied, custom playback is used, and the current ad is not AdSense/AdX. Its isCustomClickTrackingUsed() result describes the current ad, not a permanent property of the whole page.
Record the actual manager and ad associated with the observation. Do not read a variable left over from another player, a previous ad request or a manager that has already been replaced. Capture isCustomPlaybackUsed() alongside the custom-click result as diagnostic context.
| Observation | What it supports | Next step |
|---|---|---|
| No custom element supplied | No configured custom-click element for this container | Confirm whether custom behavior is required at all |
| Current custom-click result is false | This ad is not using the supplied custom-click path | Keep the custom element inactive and inspect eligibility |
| Current result is true | SDK reports using the custom element for this ad | Test placement, visibility and actual interaction |
| Result unavailable or tied to an old manager | Runtime evidence is incomplete | Reproduce with the active manager and ad |
Do not identify the entire demand mix from one sample. A page can receive different creatives on later requests. Recheck the runtime result for each relevant ad rather than caching the first answer as a device-wide capability flag.
The same reference explains that a provided alternative video element is used for custom playback only in relevant platform circumstances. Supplying that video argument alone does not establish that custom playback is active. Let the documented runtime observations guide the diagnostic.
Treat element placement and ownership as part of the contract#
The AdDisplayContainer constructor reference distinguishes the SDK's ad container from the optional custom click element. Its placement warning is specific: the custom element must not cover the video player, where it can intercept SDK controls.
Inspect the rendered geometry, not only CSS source. Record the relevant element bounds in ordinary and fullscreen presentation, after resize and on the actual affected device. A button that looks separate in the initial layout can overlap after a responsive change. Treat overlap as a hypothesis to verify, not an explanation for every failure.
Keep the SDK-owned iframe intact. The same reference says it must be preserved for SDK operation. Removing it, moving its internal controls or placing an application layer over them is not a diagnostic substitute for the supported custom-element path.
Check whether the node passed during construction is still the displayed node. In a component-based application, a later render can replace an element while old code still holds its former reference. Inspect that possibility against the actual integration; it is not a claim that a particular framework causes the problem.
Make visibility follow ad lifecycle#
The constructor reference assigns custom-element visibility to the application. It recommends checking the runtime result at STARTED to decide whether to display the element, and hiding it at CONTENT_RESUME_REQUESTED where appropriate for the UI.
Build a small state worksheet for one playback attempt:
- Before an eligible ad starts, the custom action is hidden or inactive.
- On the current ad's start, record its custom-click result and the resulting visibility decision.
- During playback, verify the displayed node and its position.
- On return to content, hide or deactivate the action.
- On error, replacement or teardown, clear application-owned state using the integration's cleanup path.
The last step is an implementation recommendation, not a claim that every termination emits the same event. A UI must not depend on a callback that was never observed on its error branch. Retain that branch as unresolved until the application handles it correctly.
Do not attach a new anonymous listener on every render without accounting for old listeners. If removing listeners through AdsManager, the current reference requires the same function reference used when registering them. Confirm which manager owns each registration and which manager receives cleanup.
A stale visible action can point at an old creative, while a stale hidden state can conceal a currently eligible action. Both are lifecycle failures even if the first ad worked. Exercise at least a subsequent ad or request in the same page session.
Separate observing clicks from providing an ad click action#
Google's mouse-click tracking guide describes observing interaction through a parent container around the content and ad players. It warns that listeners placed directly on the content video miss the overlaid ad-player path, and that showing or hiding the ad container can interfere with SDK behavior.
That observation pattern is not a general API for making an arbitrary outside button perform a supported ad click-through. A parent-container event can be useful application telemetry, but it does not establish which ad control was activated or that every reporting recipient received a request.
Keep telemetry labels honest. If you observed a container interaction, record it as that observation until the SDK event and navigation evidence support something narrower. Do not name every DOM click an accepted advertising click simply because a dashboard uses that term.
If the requirement is an always-available custom CTA across all devices, identify it as a product requirement to confirm with the supported integration. Do not turn a false runtime result into permission to simulate SDK behavior. The constructor's custom element is conditional; a style preference does not remove those conditions.
Follow the supported interaction through four checkpoints#
Use an authorized fixture or agreed QA placement. Keep the creative response, manager reference, browser/device, SDK version and interaction timestamp together. Avoid repeatedly clicking paid production advertisements to investigate a UI issue.
Record four separate outcomes:
| Checkpoint | Evidence to retain |
|---|---|
| User interaction | Which visible element received the authorized action |
| SDK observation | Relevant public event from the active manager |
| Navigation | Actual destination/redirect result, including a failed or blocked outcome |
| Reporting | Outgoing notification and available recipient/report evidence |
The current AdEvent reference distinguishes CLICK from VIDEO_CLICKED, which concerns the non-clickthrough portion of a video ad. It also defines pause and resume separately. A pause log is not a completed destination visit, and an internal debug message should not replace the public integration event.
When the SDK reports a click but navigation fails, preserve the browser outcome and investigate that boundary. When navigation succeeds but a recipient is missing, use the VAST recipient audit. Do not add a second application dispatcher merely because one reporting column is empty.
Do not manually invoke reporting URLs to make the test pass. That can create requests without the supported interaction and obscure whether the original integration works. Any separate endpoint test needs explicit authorization and its own test-traffic treatment.
A hypothetical acceptance worksheet#
Suppose a controlled QA plan includes twenty ad starts: twelve report that custom click tracking is used and eight report that it is not. All twenty are test observations, not campaign traffic or unique people.
The expected UI behavior is twelve eligible displays and eight inactive custom elements. That is an eligibility-conditioned expectation for this fixture set; the twelve-out-of-twenty share, 60%, is not a click-through rate.
For one authorized action on each of the twelve eligible displays, suppose the initial evidence is:
| Result in this hypothetical review | Test actions |
|---|---|
| Intended destination opens and required recipient evidence is available | 9 |
| Destination opens; recipient evidence unresolved | 2 |
| Navigation outcome fails or remains unresolved | 1 |
| Total eligible test actions | 12 |
The fully evidenced share is 9 / 12 = 75% of these test actions. The two reporting gaps and one navigation gap need different next steps. Neither the eligibility share nor this acceptance share measures audience engagement, invalid traffic, billed waste or refunds.
If the eight ineligible custom elements remained visible, fix that state-handling issue before interpreting their interactions as eligible failures. Retain those observations; do not quietly discard them from a report to make the apparent success rate improve.
Close the integration with a reproducible matrix#
Repeat the agreed checks across the supported environment set. Include eligible and ineligible ads, the first and a later ad, ordinary and fullscreen layouts where supported, resize, content return, error and teardown. Mark branches untested when no suitable fixture was available.
For each branch, retain the current-ad eligibility result, actual geometry, visibility transition, interaction, public SDK event, navigation result and permitted reporting evidence. Capture only information needed for the investigation; redact credentials and personal identifiers before sharing the packet.
Change one evidenced cause at a time. A repair to element placement does not automatically repair callback cleanup or receiver reporting. Confirm that the tested code and creative are the versions subsequently served before calling the integration accepted.
For campaigns already sending supported events to AdProof, prepare a campaign/date/timezone-scoped export of available delivery evidence and keep the filters explicit. Compare it alongside the runtime packet; it does not automatically recover browser events or third-party receiver logs.
The anonymized streaming-publisher verification case illustrates scoped impression reconciliation, not a custom-button certification. Bring the affected campaign scope and click-path evidence to AdProof to establish which received signals support the review.
Frequently asked questions#
Why is isCustomClickTrackingUsed false after I supply an element?
Supplying an element is only part of the contract. Current-ad custom playback and creative eligibility also matter. Read the runtime result from the active manager at the documented start checkpoint; do not assume the supplied constructor argument makes the path active everywhere.
Should the custom click element cover the video?
No. The constructor documentation warns against covering the player because the element can intercept SDK controls. Verify its actual position after layout changes and manage its visibility explicitly in the application.
Does a true result prove click-through and tracking work?
No. It establishes the SDK's current-ad custom-click state. Test the authorized interaction, public event, navigation and recipient evidence separately, and preserve any unresolved boundary.
Can a parent-container click listener replace the ad click-through?
No such equivalence follows from the mouse-click guide. That guide provides an interaction-observation pattern. A container event alone does not establish an eligible ad click, successful navigation or accepted reporting.
Check click-element eligibility for the ad
Record SDK eligibility, element placement and visibility through the ad lifecycle.
Use the tracking QA checklistOpens a practical guide. No email required.
