> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to connect

> How to connect the Matomo data source to Adriel: generate a token_auth value, enter the Matomo URL and Site ID, and import site analytics.

Matomo (formerly Piwik) is an open-source web-analytics platform, deployable either self-hosted or as a managed service through Matomo Cloud. Connecting it reads visits, page views, events, and goal conversions at the site level into Adriel dashboards using the Matomo Reporting API.

## Before you connect

The following are required:

* A Matomo account.
* A Matomo instance, either self-hosted or on Matomo Cloud.
* The Matomo base URL (for example, `https://analytics.example.com` or `https://yourcompany.matomo.cloud`).
* A Matomo `token_auth` value generated by a user with read access to the target site.
* The numeric Site ID of the website to be imported.
* Adriel's IP address (`3.37.49.210`) allow-listed on the Matomo instance.

## Connect Matomo

<Steps>
  <Step title="Generate a Matomo token_auth value">
    Follow the steps for the Matomo version in use.

    For **Matomo 4 or newer**:

    1. Sign in to Matomo.
    2. Click the top menu to open **Matomo Admin**.
    3. Go to **Personal** > **Security**.
    4. Scroll to the bottom and click **Create new token**.
    5. Confirm the account password and enter the purpose for issuing the token.
    6. Select that the token should be valid only for secure requests.
    7. Click **Create new token** to generate it, then copy the value. Matomo displays it once.

    For **Matomo 3 or older (Piwik)**:

    1. Sign in to Matomo (Piwik).
    2. Click **Administration** in the top menu.
    3. Click **API** in the left menu and retrieve the token.

    The `token_auth` feature is not available for the WordPress edition of Matomo.
  </Step>

  <Step title="Open the connector in Adriel">
    On the **Data Sources** page, search for **Matomo** and select it.
  </Step>

  <Step title="Enter the connection details">
    Fill in the required fields:

    * **Domain**: the full Matomo base URL. A widgetize dashboard URL (Matomo > **Settings** > **Export** > **Widgets** > **Widgetize dashboards**) is also valid.
    * **Token Auth**: the token generated in the first step.
  </Step>

  <Step title="Select the site">
    Choose the **ID site** to connect from the dropdown. Websites linked to the Matomo account under the **All Websites** tab appear in this list.
  </Step>

  <Step title="Submit">
    Click **Submit** to complete the connection. Initial data availability can take up to one business day.
  </Step>
</Steps>

## What gets imported

The connector imports visit, behavior, and engagement metrics (visits, unique visitors, page views, bounce rate, average time on site), goal conversions and revenue, and breakdowns covering source attribution, page, device, and geography.

For the complete list of metrics and breakdowns, see the [Matomo data reference](/data-sources/g-n/matomo/data-reference).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication fails after entering credentials">
    The Matomo base URL must point to the root of the Matomo instance (for example, `https://analytics.example.com`), not to a specific report URL. Confirm the URL and token were generated from the same Matomo instance and that the user account retains read access to the target site.
  </Accordion>

  <Accordion title="Reports return no rows for a site">
    Each data source is scoped to a single Site ID. Verify the Site ID matches the website intended for import and that the user backing the token has access to that site.
  </Accordion>

  <Accordion title="Self-hosted Matomo instance is not reachable">
    The Matomo instance must be reachable from the public internet for the connector to query it. Internal-only deployments require either a public endpoint or an allow-listed network path before the connection can succeed.
  </Accordion>

  <Accordion title="Token stops working after a user change">
    Tokens are tied to the Matomo user that generated them. If that user is removed or loses access to the site, every subsequent request fails. Re-save the connection with a new token generated by a user that retains read access.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Matomo data reference" href="/data-sources/g-n/matomo/data-reference">
    Metrics, breakdowns, and limits for Matomo.
  </Card>

  <Card title="Matomo FAQs" href="/data-sources/g-n/matomo/faqs">
    Common questions and expected behaviors for the Matomo data source.
  </Card>

  <Card title="How to connect etracker" href="/data-sources/a-f/etracker/how-to-connect">
    Connect another privacy-focused web-analytics platform.
  </Card>

  <Card title="How to connect Piano Analytics" href="/data-sources/o-z/piano-analytics/how-to-connect">
    Connect another European-focused web-analytics platform.
  </Card>
</CardGroup>