Track Element Clicks on a Page Using an App Dataset

1. The report is embedded via the standard Embed Code as "Tile", "Live Dashboard", or "Viewer" (any "Show Report in" setting): Metric Insights already logs the view automatically; no custom tracking is needed.
   • Check the Element's Engagement tab in the Viewer, or Content > Content Center, to confirm.
2. The report is embedded via the "Preview" embed type, or hand-coded, and the link points to a real Metric Insights Element you have view access to (you know its Element ID and, if segmented, its Segment Value ID). You just want the click to count as a normal Engagement view: Call POST /api/element_views?element_id={elementId}&segment_value_id={segmentValueId} from the App's JavaScript (credentials: 'include' to use the logged-in session). This is the simplest option with no App Entity or Dataset required. It writes into the exact same Engagement data as case 1.
   • It only increments a view count for that Element, with no REST read-back of individual click rows (only aggregate counts, self-scoped to the calling user, via a plain GET; PUT/DELETE are not supported on this endpoint).
3. The link is hand-coded and isn't a real registered Element (an arbitrary external URL with no Element ID), or you do not need it in Engagement reporting specifically and just want to record that it was clicked: Use the built-in MI.PortalPageView.logClick() instead. See How Do I Track Usage of a Portal Page for configuration details.
   • No App Entity or Dataset is required, but the logged data (portal_page_link) has no REST read-back; querying it back needs direct SQL access to the dashboard database.
4. You want a usage report built inside the App itself, queryable over REST with no SQL access, with your own custom fields: Cases 1 to 3 only tell you whether Metric Insights already counts the click as a view. If you need the click data as your own reportable Dataset (individual rows, custom fields, editable or deletable rows, or cross-user access without SQL), follow the rest of this article to build a custom App Dataset Entity.

Access App > Entities tab

1. [+ Add App Entity]
2. Name: Enter an Entity name, for example click_tracking.
3. Entity Type: Internal.
4. Activate the Is App Dataset checkbox.
5. In the Dataset field that now appears, select the Dataset you created in step 1.
6. [Save]

1. Bind a single click handler to a container selector, not one handler per link, so any current or future link inside it is tracked automatically. Source the values you want to log however suits your own code:

<ul class="tracked-links">
  <li>
    <a href="https://example.com/reports/q4-revenue-summary"
       target="_blank" rel="noopener noreferrer">
      External Report - Q4 Revenue Summary
    </a>
  </li>
</ul>

2. Replace {appName} with the App's "Name used in URL" (not its numeric ID) and {entityName} with the Entity name defined above. Do not include a user_id field; the server stamps the owner automatically from the logged-in session.

// Log a click. POST an array of rows to the Entity's data endpoint.
document.querySelector('.tracked-links').addEventListener('click', (event) => {
  const link = event.target.closest('a');
  if (!link) return;
  fetch('/data/page/{appName}/{entityName}', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    credentials: 'include',
    // Always POST an array, even for a single row. The server rejects a bare
    // object here with "Invalid data format".
    body: JSON.stringify([{
      element_name: link.textContent.trim(),
      click_timestamp: new Date().toISOString(),
      opened_in_tab: link.target === '_blank' ? 'Y' : 'N',
      // Add any other fields your Entity defines.
    }]),
  })
    .then((r) => r.json())
    .then((d) => console.log('Logged:', d));
});

// Read the logged rows back with a GET to the same endpoint.
// PUT and DELETE are also supported on this endpoint.
fetch('/data/page/{appName}/{entityName}', { credentials: 'include' })
  .then((r) => r.json())
  .then((rows) => console.log('Logged clicks:', rows));

The fields you send here are exactly what you'll query back and report on in the next section. Because the App Dataset auto-detects its schema, any keys you include become columns. Send a consistent set of fields on every click so the report stays uniform, for example the Element name, a timestamp, and whether the Element opened in a new tab. The row's owner (owner_user_id) is added automatically by the server and does not need to be sent. See Overview of Apps (Portal Pages) for more on configuring App Entities generally.

Query the App Dataset from the App's JavaScript to build a usage summary or report. The response is an object with a data array containing the stored rows. The same endpoint also supports PUT and DELETE requests to update or remove logged rows.

fetch('/data/page/{appName}/{entityName}', {
  method: 'GET',
  credentials: 'include'
})
.then(r => r.json())
.then((response) => {
  const rows = response.data; // [{ element_name, click_timestamp, opened_in_tab, ... }, ...]
  console.log('Usage summary:', rows);
});

The same data path also supports updating and deleting rows: send a PUT request to modify existing records and a DELETE request to remove them. Use the returned rows to render tables, charts, or aggregated usage metrics directly within the App.