HeatmapService

Ingests touch interaction events from mobile clients and provides aggregated heatmap data for analytics.

Methods

Method	Description
IngestTouchEvents	Record touch events from a device
QueryHeatmapData	Query aggregated heatmap data
ListScreenshots	List screenshots for a screen
UploadScreenshot	Upload a screenshot as a heatmap backdrop

IngestTouchEvents

Record touch interaction events (taps, scrolls, action clicks) from the mobile app.

Authorization: Authenticated user

Request: IngestTouchEventsRequest

Field	Type	Description
events	TouchEvent[]	Batch of touch events. Max 500 per request.

Response: IngestTouchEventsResponse

Field	Type	Description
ingested_count	int32	Number of events ingested.

TouchEvent

Field	Type	Description
screen_name	string	Screen identifier. Max 200 characters.
x	float	Content-relative X coordinate (0.0–1.0).
y	float	Content-relative Y coordinate (0.0–1.0).
timestamp	Timestamp	When the event occurred.
campaign_id	string	Associated campaign ID.
event_type	TouchEventType	Type of event (TAP, SCROLL, ACTION_CLICK).

QueryHeatmapData

Query aggregated heatmap data for a screen.

Authorization: Requires PERMISSION_CAMPAIGNS_READ permission

Request: QueryHeatmapDataRequest

Field	Type	Description
screen_name	string	Screen to query.
campaign_id	string	Filter by campaign ID.
mode	HeatmapMode	Aggregation mode (ALL_USERS or PER_USER).
user_id	string	Filter by user ID (for PER_USER mode).
event_types	TouchEventType[]	Filter by event type.

Response: QueryHeatmapDataResponse

Field	Type	Description
data_points	HeatmapDataPoint[]	Aggregated heatmap data points.
user_touch_counts	UserTouchCount[]	Per-user touch counts (PER_USER mode).

ListScreenshots

List uploaded screenshots for a screen.

Authorization: Requires PERMISSION_CAMPAIGNS_READ permission

Request: ListScreenshotsRequest

Field	Type	Description
screen_name	string	Screen name to list screenshots for.

Response: ListScreenshotsResponse

Field	Type	Description
screenshots	ScreenScreenshot[]	List of screenshots.

UploadScreenshot

Upload a screenshot image as a heatmap backdrop.

Authorization: Requires PERMISSION_CAMPAIGNS_READ permission

Request: UploadScreenshotRequest

Field	Type	Description
screen_name	string	Screen the screenshot is for.
image_data	bytes	Screenshot image data (PNG).
width	int32	Image width in pixels.
height	int32	Image height in pixels.

Response: UploadScreenshotResponse

Field	Type	Description
screenshot	ScreenScreenshot	The uploaded screenshot metadata.

Enums

HeatmapMode

Value	Description
ALL_USERS	Aggregate data across all users
PER_USER	Show data grouped by individual user

TouchEventType

Value	Description
TAP	User tapped the screen
SCROLL	User scrolled content
ACTION_CLICK	User clicked an action button