v2.18.0

[mikecao]

Features

Attribution report

The new Attribution report allows you to trace the source origin of a user so that you can measure the effectiveness of your ad campaigns and optimize your spend. This report also integrates revenue data so you can see which channels contribute the most to your sales.

Read docs.

Distinct ID

We are introducing a new property for sessions called the distinct ID. This is a new parameter that lets you assign a ID to a session to help you identify a user later.

To set a distinct ID, use the umami.identify method from the tracker.

umami.identify('[email protected]');

In a server environment, you would send an event payload with a id parameter.

{
  "payload": {
    "hostname": "your-hostname",
    "language": "en-US",
    "referrer": "",
    "screen": "1920x1080",
    "title": "dashboard",
    "url": "/",
    "website": "your-website-id",
    "id": "[email protected]"
  },
  "type": "event"
}

You can then search the distinct ID from the Sessions screen.

Read docs.

data-before-send attribute

We are introducing a new tracker attribute data-before-send that let's you define a function that will be called before data is sent. You can then inspect and modify the payload or cancel the send entirely. The function will take two parameters, type and payload. To continue with sending, you return a payload object. To cancel the send, return a false-y value.

First, define the function to be called.

function beforeSendHandler(type, payload) {
  if (checkPayload(payload)) {
    return payload;
  }
  return false;
}

Then pass the name of the function using the data-before-send attribute.

<script defer
  src="/script.js"
  data-website-id="7801d46c-afd2-424c-8680-4ea713b2002a"
  data-before-send="beforeSendHandler"></script>

Events chart filtering

You can now filter custom events by clicking on an item in the events table.

Alternative host for icons

The default host we use for displaying website favicons is icons.duckduckgo.com. Now you can use an alternative host with the environment variable FAVICON_URL. You need to pass a string with a token to replace the domain name. For example:

https://icons.duckduckgo.com/ip3/{{domain}}.ico

Some alternatives you can use:

https://www.google.com/s2/favicons?domain={{domain}}
https://logo.clearbit.com/{{domain}}

Migrations

This release includes some database migrations that add new columns for handling UTM parameters. The migrations will
automatically run during the build process.

The migrations will only apply the new schema but not do any migration of old data. The reason for this is we didn't
want to hang up the build process for users with lots of data. Instead we will be providing scripts that you can run to migrate your
data separately.

To migrate your data for this release, use the SQL for your database from here

Fixes

• Empty event search Empty event search #3329
• Realtime activity details not listed from newest to oldest Realtime activity details not listed from newest to oldest #3330
• POST /api/auth/very Method not allowed | Outdated documentation? POST /api/auth/very Method not allowed | Outdated documentation? #3339
• Null region breaks Insights Report Null region breaks Insights Report #3344
• Docker middleware An alternative to Docker middleware #3357
• CORS errors in Docker CORS errors #3307
• API requests are ignored if User-Agent is empty batch API requests are ignored if User-Agent is empty #3337
• Referrer data displayed in every table Referrer data displayed in every table #3284
• Realtime View Graph and Activity are not in sync Realtime View Graph and Activity are not in sync #3244

Updates

• Upgraded Next to 15.3.1
• Upgraded Prisma to 6.7.0

Thanks

@harryo @Cibiyanna26 @YoSev @Maxime-J @perso182 @astappiev @thomasdn @YektaDev @gjelbrim

---

This discussion was created from the release v2.18.0.

[Matthijz98]

It would be cool if the data migration would be added as npm script/command or something.
Then adding some basic error catching and feedback to the user could be added.

[trondkla]

Thanks for getting out Distinct IDs this fast <3

[emschwartz]

Thanks for this release! Distinct IDs are very useful.

Previously, umami.identify took a JSON object. Is there a way to migrate the old data such that one of those keys is used as the distinct ID?

[mikecao]

Something like this should do it:

update session
set distinct_id = d.string_value
from session_data d
where session.session_id = d.session_id
and d.data_key = 'your_distinct_id';

[emschwartz]

Perfect, thanks!

[bigbasti]

Regarding Distinct ID, when I identify three (parallel) sessions as UserA, will umami then count all three sessions as one visit? Or will Umami still report three distinct visits in the statistics?

Thanks!

[mikecao]

It's still separate visits. Think of it more as tying different sessions together.

[sunech]

Great update 👌

The 09_update_hostname_region migration was a bit heavy to run with a lot of data. Took a few hours just to complete the UPDATE on website_event with 36m records 🙈

The postgres data migration query unfortunately failed, as there were UTM values exceeding the capacity fields:
ERROR: value too long for type character varying(255)

Used a truncating query as fallback instead:

SET fbclid = url.fbclid,
    gclid = url.gclid,
    li_fat_id = url.li_fat_id,
    msclkid = url.msclkid,
    ttclid = url.ttclid,
    twclid = url.twclid,
    utm_campaign = url.utm_campaign,
    utm_content = url.utm_content,
    utm_medium = url.utm_medium,
    utm_source = url.utm_source,
    utm_term = url.utm_term
FROM (
    SELECT event_id, website_id, session_id,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)fbclid=([^&]+)', 'i'))[1], 255) AS fbclid,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)gclid=([^&]+)', 'i'))[1], 255) AS gclid,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)li_fat_id=([^&]+)', 'i'))[1], 255) AS li_fat_id,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)msclkid=([^&]+)', 'i'))[1], 255) AS msclkid,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)ttclid=([^&]+)', 'i'))[1], 255) AS ttclid,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)twclid=([^&]+)', 'i'))[1], 255) AS twclid,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)utm_campaign=([^&]+)', 'i'))[1], 255) AS utm_campaign,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)utm_content=([^&]+)', 'i'))[1], 255) AS utm_content,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)utm_medium=([^&]+)', 'i'))[1], 255) AS utm_medium,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)utm_source=([^&]+)', 'i'))[1], 255) AS utm_source,
        LEFT((regexp_matches(url_query, '(?:[&?]|^)utm_term=([^&]+)', 'i'))[1], 255) AS utm_term
    FROM website_event
) url
WHERE we.event_id = url.event_id
  AND we.session_id = url.session_id
  AND we.website_id = url.website_id;```

[rakurtz]

thanks for your awesome work. i was updating umami according to the docs via docker compose pull and docker compose up -d --force-recreate umami . I wonder if this also did the database schema migration (not the existing data, just the schema).

The blog post states "The migrations will automatically run during the build process." But upgrading via the docker image is not a build process technically, is it?

Do i manually have to invoke the schema migration somehow?

Thanks in advance

[mikecao]

No, when you start the container, it will run migrations (if any) at that point.

[rakurtz]

Thanks. Yes, I was abled to see that in the container's logs.