标记管理器上下文中的触发器允许您定义应该在哪个事件上触发或阻止某个标记。例如,当单击特定元素时,或者当访问者到达某个滚动位置时。
Matomo让您轻松地创建一个新的触发器。创建新触发器时,请考虑将此新触发器贡献给官方标签管理器插件通过创建一个拉请求。
标签、触发器和变量都以相同的方式实现,只是JavaScript部分略有不同。一旦您知道如何开发触发器,您还将能够开发标记和变量。
我们将创建一个新的触发器,当在线状态从在线变为离线或相反时,该触发器将被触发。为了展示带有触发器参数的示例,我们还提供了仅在用户联机或脱机时触发事件的可能性。
要创建一个新的触发器,您应该使用CLI工具并执行以下命令:
$ ./console generate:tagmanager-trigger
这个命令将指导您创建触发器,并询问一些事情,如插件的名称和您想要创建的触发器的名称。当它要求您输入触发器名称时,输入“在线更改”。命令创建以下文件:
插件/ yourplugin美元/模板/触发/ OnlineChangeTrigger.php
允许您定义例如触发器的类别和定义参数。插件/ yourplugin美元/模板/触发/ OnlineChangeTrigger.web.js
让您实现JavaScript逻辑来检测在线状态的变化。当您生成触发器时,生成器将自动创建一些触发器翻译键在你的插件/ $ yourplugin / lang / en.json
文件。你可能想要调整创建的键的翻译:
"OnlineChangeTriggerName": "在线更改","OnlineChangeTriggerDescription": "这是在线更改的描述","OnlineChangeTriggerHelp": ""
或者,还可以设置名称、描述和可选帮助文本OnlineChangeTrigger.php
但建议使用翻译键,以便其他开发人员可以将其翻译成不同的语言。
理想情况下,描述应该保持相当短,在一句话之内。通常不需要帮助文本,但是如果您想更详细地描述触发器,或者想向用户提供有关触发器实际功能的进一步说明,则可能会有用。
在生成的OnlineChangeTrigger.php
,您将发现一个名为getCategory ()
.在这里,您可以定义触发器最适合的类别。您可以从一组预定义的类别中选择,如“页面视图”,“点击”和“用户约定”,或创建您自己的类别:
公共函数getCategory(){返回self::CATEGORY_OTHERS;}
在本例中,我们使用预定义的类别“Others”。要使用自定义类别,只需返回您想要选择的类别的名称:
公共函数getCategory(){返回'Network';}
你可以选择为你的触发器显示一个图标。您所需要做的就是在方法中返回图标文件的路径getIcon ()
是这样的:
公共函数getIcon(){返回'plugins/TagManager/images/MyIcon.png';}
我们建议你把图片放在图片
插件的文件夹。例如,文件本身可能是ajpg
,png
,或svg
理想大小为64x64像素的文件。
在本例中,我们希望让用户配置应该触发哪些事件。为此,我们可以配置参数。参数具有相同的API插件设置.
下面是一个关于如何定义参数的示例,您可以稍后在JavaScript部分中使用该参数进行访问parameters.get(“listenEvent”)
.
公共函数getParameters(){返回数组($this-> makessetting ('listenEvent', 'all', FieldConfig::TYPE_STRING,函数(FieldConfig $field) {$field->title = '当网络状态变为'时触发;$field->uiControl = FieldConfig::UI_CONTROL_SELECT;$field->availableValues = array('all' => '在线或离线','Online' => '在线','Offline' => '离线',);}));}
了解更多关于指定参数在我们的专用标签管理器-参数指南。
现在我们开始开发JS部分,它将在在线状态发生变化时触发事件。这是在文件中完成的OnlineChangeTrigger.web.js
.基本结构如下所示:
(function(){返回函数(参数,TagManager) {this。设置= function (triggerEvent) { // accessing a parameter var listenEvent = parameters.get('listenEvent'); // ... // triggerEvent({event: '$MyPlugin.$eventName', 'OptionallyOtherVariables': 'variable value'}); // ... }; }; })();
实现的触发器示例可能是这样的:
(function(){返回函数(参数,TagManager) {this。设置= function (triggerEvent) { var listenEvent = parameters.get('listenEvent'); if (listenEvent === 'all' || listenEvent === 'offline') { TagManager.dom.addEventListener(parameters.window, 'offline', function (event) { triggerEvent({event: 'MyPlugin.OnlineStatusChange', 'MyPlugin.OnlineStatus': 'offline'}); }); } if (listenEvent === 'all' || listenEvent === 'online') { TagManager.dom.addEventListener(parameters.window, 'online', function (event) { triggerEvent({event: 'MyPlugin.OnlineStatusChange', 'MyPlugin.OnlineStatus': 'online'}); }); } }; }; })();
在上面的示例中,我们定义了一个匿名JavaScript类,该类实现了一个方法设置
.这个方法在加载标记管理器时立即执行。您可以访问您所定义的任何参数参数。(“parameterName美元”,optionalDefaultValueIfNoneConfigured)
.你可能还注意到我们使用TagManager.dom.addEventListener
而不是window.addEventListener
.原因是TagManager.dom.addEventListener
将跨浏览器工作。
要触发事件,只需调用该方法triggerEvent (dataLayerObject)
.的dataLayerObject
通常应该包含一个描述性的事件
属性以插件名为前缀(例如并且。OnlineStatusChange
),以及可选的多个描述该事件的属性,这样就可以通过数据层访问这些属性。
通过参数
变量,您可以访问一些特殊的属性,如文档
而且窗口
.例如parameters.document
或parameters.window
.的访问parameters.document
在文档
推荐直接使用,因为它使单元测试更容易。你可以在TemplateParametersAPI参考。
您还可以访问TagManager
实例,它提供了很多围绕DOM、窗口、url、事件、数据层等的帮助实用程序。你可以在TagManagerAPI参考。
您可能已经注意到,我们已经指定了一个属性并且。OnlineStatus
在触发事件中。您可能希望为此创建一个预先配置的变量,以便用户可以使用该变量作为触发条件(筛选器)。这甚至会使参数listenEvent
在上面的例子中过时了,因为他们可以通过一个条件来限制触发器,例如只监听在线
的地位。
使用实例生成一个预配置变量。
$ ./console生成:tagmanager-datalayer-variable
如果输入变量名在线状态
,一个名为插件/ $ yourPlugin /模板/变量/预配置/ OnlineStatusVariable.php
将被创建。
您可能注意到,配置名称、描述、类别等与配置触发器或常规变量的方式相同。
作为一个类别,我们建议设置触发器的名称,将该触发器的所有预配置变量分组到一个类别中:
公共函数getCategory(){返回'在线';}
为了实现这个变量,我们必须在方法中返回数据层属性的名称getDataLayerVariableName
.我们可以创建一个文件插件/ $ yourPlugin /模板/变量/预配置/ OnlineStatusVariable.web.js
相反,由于这类变量经常被创建,我们为它创建了这样的快捷方式:
protected函数getDataLayerVariableName(){返回'MyPlugin.OnlineStatus';}
这将自动为该变量创建一个方法,该方法将返回值并且。OnlineStatus
来自数据层。
重新加载时,新创建的变量将可作为触发器中的条件被选择,也可用于其他可以选择变量的地方。