Added documentation for goal attribution

[AltamashShaikh]

Description:

Added documentation for goal attribution.
Fixes: #PG-2659

Review

• Functional review done
• Potential edge cases thought about (behavior of the code with strange input, with strange internal state or possible interactions with other Matomo subsystems)
• Usability review done (is anything maybe unclear or think about anything that would cause people to reach out to support)
• Security review done
• Wording review done
• Code review done
• Tests were added if useful/possible
• Reviewed for breaking changes
• Developer changelog updated if needed
• Documentation added if needed
• Existing documentation updated if needed

[sgiehl]

This might actually not always be true. This only works when using javascript tracking and only if the javascript tracker method setConversionAttributionFirstReferrer wasn't called.

[AltamashShaikh]

should we say by default for javascript tracker if that's the case? or it will attribute to first if setConversionAttributionFirstReferrer was called?

Suggested change

	"AttributionDocumentation": "Conversion metrics in tables with Goal metrics are attributed to the last non-direct channel that brought visitors who converted.",
	"AttributionDocumentation": "Conversion metrics in tables with Goal metrics are attributed to the last non-direct channel, if `setConversionAttributionFirstReferrer` was called it will attribute to first non-direct channel that brought visitors who converted.",

[AltamashShaikh]

cc: @Stan-vw

[sgiehl]

As conversion attribution is a bit more complexe and might be subject to change I think we should maybe only mention the default case and create and link to a FAQ that documents the behavior and possibilities a bit more detailed.

[Stan-vw]

Do we have a FAQ that documents this behaviour?

• if so, I suggest we change the line to "By default, conversion metrics in tables with Goal metrics are attributed to the last non-direct channel that brought visitors who converted. Learn more about conversion attribution." where the hyperlink goes to the complementary FAQ
• if not, I suggest we change the line to "By default, conversion metrics in tables with Goal metrics are attributed to the last non-direct channel that brought visitors who converted. "

[sgiehl]

I don't know if there is an FAQ.
But keep in mind, that last non-direct might not be correct in all cases.
When the visitor was visiting the page with campaign parameters in a previous visit, a conversation would be attributed to this campaign even if the conversions visit was coming from another non-direct referer like a search engine.

[AltamashShaikh]

this is the FAQ we have
@sgiehl will this be fine ?

Suggested change

	"AttributionDocumentation": "Conversion metrics in tables with Goal metrics are attributed to the last non-direct channel that brought visitors who converted.",
	"AttributionDocumentation": "By default, conversion metrics in tables with Goal metrics are attributed to the last non-direct channel that brought visitors who converted. %1$sLearn more%2$s about conversion attribution."

[Stan-vw]

That sounds right to me @AltamashShaikh , thanks for progressing this so rapidly 👍

[AltamashShaikh]

Updated

[mattab]

btw The FAQ would probably be more this one: https://matomo.org/faq/general/what-is-the-default-attribution-model-used-in-matomo/

For now I'll move this to a future milestone along with the other relevant: #20516 #20515

[AltamashShaikh]

@sgiehl Can we merge this ?

[sgiehl]

I'm still not sure if we should add that, as it's not correct in various cases (not even the default one):

• For attribution campaigns are always preferred. So even if a visitor came from a search engine last, the conversion will be attributed to a campaign, if one was present in a previous visit
• Attribution to any previous non-direct referrer only works when using javascript tracking and if cookies are enabled. In any other case conversions will be attributed to the current visits referrer.

I really think it's good to document that in the software and in FAQs, but adding documentation that isn't correct is ihmo worthless. But if @Stan-vw and @mattab have another opinion on that, I'm happy to discuss and merge it if needed.

[mattab]

Thanks for your feedback

1. For attribution campaigns are always preferred. So even if a visitor came from a search engine last, the conversion will be attributed to a campaign, if one was present in a previous visit

This is actually a bug, I'll create an issue for it

2. Attribution to any previous non-direct referrer only works when using javascript tracking* and if cookies are enabled**. In any other case conversions will be attributed to the current visits referrer.

I thought attribution would also work without cookies, because the log_visit row has the channel/referrer information, and this is copied in the log_conversion row during the conversion, right? Or is this not how it works?

[sgiehl]

I thought attribution would also work without cookies, because the log_visit row has the channel/referrer information, and this is copied in the log_conversion row during the conversion, right? Or is this not how it works?

No it doesn't. If no value is passed by javascript, it will use the currents visits referrer. There are no look ups for previous referrers of the same visitor or similar, which would be needed to attribute it to e.g. last/first non-direct referrer or similar.
This is the method to handle the conversion attribution:

matomo/plugins/Referrers/Columns/Base.php

Lines 612 to 680 in df8fe4f

	public function getValueForRecordGoal(Request $request, Visitor $visitor)
	{
	$referrerUrl = $request->getParam('_ref');
	$referrerCampaignName = $this->getReferrerCampaignQueryParam($request, '_rcn');
	$referrerCampaignKeyword = $this->getReferrerCampaignQueryParam($request, '_rck');
	// Attributing the correct Referrer to this conversion.
	// Priority order is as follows:
	// 0) In some cases, the campaign is not passed from the JS so we look it up from the current visit
	// 1) Campaign name/kwd parsed in the JS
	// 2) Referrer URL stored in the _ref cookie
	// 3) If no info from the cookie, attribute to the current visit referrer
	Common::printDebug("Attributing a referrer to this Goal...");
	// 3) Default values: current referrer
	$type = $visitor->getVisitorColumn('referer_type');
	$name = $visitor->getVisitorColumn('referer_name');
	$keyword = $visitor->getVisitorColumn('referer_keyword');
	// 0) In some (unknown!?) cases the campaign is not found in the attribution cookie, but the URL ref was found.
	// In this case we look up if the current visit is credited to a campaign and will credit this campaign rather than the URL ref (since campaigns have higher priority)
	if (
	empty($referrerCampaignName)
	&& $type == Common::REFERRER_TYPE_CAMPAIGN
	&& !empty($name)
	) {
	// Use default values per above
	Common::printDebug("Invalid Referrer information found: current visitor seems to have used a campaign, but campaign name was not found in the request.");
	} // 1) Campaigns from 1st party cookie
	elseif (!empty($referrerCampaignName)) {
	$type = Common::REFERRER_TYPE_CAMPAIGN;
	$name = $referrerCampaignName;
	$keyword = $referrerCampaignKeyword;
	Common::printDebug("Campaign information from 1st party cookie is used.");
	} // 2) Referrer URL parsing
	elseif (!empty($referrerUrl)) {
	$idSite = $request->getIdSite();
	$referrer = $this->getReferrerInformation($referrerUrl, $currentUrl = '', $idSite, $request, $visitor);
	// if the parsed referrer is interesting enough, ie. website, social network or search engine
	if (in_array($referrer['referer_type'], [Common::REFERRER_TYPE_SEARCH_ENGINE, Common::REFERRER_TYPE_WEBSITE, Common::REFERRER_TYPE_SOCIAL_NETWORK])) {
	$type = $referrer['referer_type'];
	$name = $referrer['referer_name'];
	$keyword = $referrer['referer_keyword'];
	Common::printDebug("Referrer URL (search engine, social network or website) is used.");
	} else {
	Common::printDebug("No referrer attribution found for this user. Current user's visit referrer is used.");
	}
	} else {
	Common::printDebug("No referrer attribution found for this user. Current user's visit referrer is used.");
	}
	$this->setCampaignValuesToLowercase($type, $name, $keyword);
	$fields = [
	'referer_type' => $type,
	'referer_name' => $name,
	'referer_keyword' => $keyword,
	];
	if (array_key_exists($this->columnName, $fields)) {
	return $fields[$this->columnName];
	}
	return false;
	}

[mattab]

Thanks @sgiehl from our discussion i created 2 follow up issues

#20515
#20516

[github-actions]

This issue is in "needs review" but there has been no activity for 7 days. ping @matomo-org/core-reviewers

[github-actions]

This PR was last updated more than one month ago, maybe it's time to close it. Please check if there is anything we still can do or close this PR. ping @matomo-org/core-reviewers

[mattab]

@sgiehl Q: Could we maybe merge this PR or is logically incorrect to a point we can't merge it?

[sgiehl]

The added details are not fully correct. So I don't see any benefit in merging it.
As mentioned on a couple of other issues. We should define how the attribution should work from a product point of view and afterwards check if Matomo works correctly. Once that was confirmed or accordingly adjusted we can create a proper attribution flow chart and a useful documentation around it. Afterwards we can also add some links to the documentation from within Matomo.

[mattab]

I wonder what the text would read, if it was to be 100% correct? Would that somehow be possible maybe, with the current way attribution works?

[sgiehl]

The attribution currently depends on various things. There are various configurations that affect the attribution, and it depends on the javascript tracker, e.g. if cookies can be used or not and if the tracker method to change the attribution has been used or not.

To me the implementation of the attribution is currently very fragile and I'm not sure if it works correctly in all cases. But I really don't want to spent more time onto investigating how it currently works without knowing how it actually should work.