Piwik\Plugin\Dimension\

ConversionDimension

Since Piwik 2.5.0

Defines a new conversion dimension that records any visit related information during tracking.

You can record any visit information by implementing one of the following events: onEcommerceOrderConversion(), onEcommerceCartUpdateConversion() or onGoalConversion(). By defining a $columnName and $columnType a new column will be created in the database (table log_conversion) automatically and the values you return in the previous mentioned events will be saved in this column.

You can create a new dimension using the console command ./console generate:dimension.

Constants

This abstract class defines the following constants:

TYPE_DIMENSION

Can be used along with setType().

Properties

This abstract class defines the following properties:

  • $columnName ash; This will be the name of the column in the database table if a $columnType is specified. Inherited from Dimension
  • $columnType ash; If a columnType is defined, we will create a column in the MySQL table having this type. Inherited from Dimension
  • $type ash; Defines what kind of data type this dimension holds. Inherited from Dimension
  • $namePlural ash; Translation key for name plural Inherited from Dimension
  • $segmentName ash; By defining a segment name a user will be able to filter their visitors by this column. Inherited from Dimension
  • $suggestedValuesCallback ash; Sets a callback which will be executed when user will call for suggested values for segment. Inherited from Dimension
  • $acceptValues ash; Here you should explain which values are accepted/useful for your segment, for example: "1, 2, 3, etc." or "comcast.net, proxad.net, etc.". Inherited from Dimension
  • $sqlSegment ash; Defines to which column in the MySQL database the segment belongs (if one is conifugred). Inherited from Dimension
  • $sqlFilter ash; Interesting when specifying a segment. Inherited from Dimension
  • $sqlFilterValue ash; Similar to $sqlFilter you can map a given segment value to another value. Inherited from Dimension
  • $allowAnonymous ash; Defines whether this dimension (and segment based on this dimension) is available to anonymous users. Inherited from Dimension
  • $dbTableName ash; The name of the database table this dimension refers to Inherited from Dimension
  • $metricId ash; By default the metricId is automatically generated based on the dimensionId. Inherited from Dimension

$columnName

This will be the name of the column in the database table if a $columnType is specified.

Signature

  • It is a string value.

$columnType

If a columnType is defined, we will create a column in the MySQL table having this type.

Please make sure MySQL understands this type. Once you change the column type the Piwik platform will notify the user to perform an update which can sometimes take a long time so be careful when choosing the correct column type.

Signature

  • It is a string value.

$type

Defines what kind of data type this dimension holds.

By default the type is auto-detected based on $columnType but sometimes it may be needed to correct this value. Depending on this type, a dimension will be formatted differently for example.

Signature

  • Its type is not specified.

$namePlural

Translation key for name plural

Signature

  • Its type is not specified.

$segmentName

By defining a segment name a user will be able to filter their visitors by this column.

If you do not want to define a segment for this dimension, simply leave the name empty.

Signature

  • Its type is not specified.

$suggestedValuesCallback

Sets a callback which will be executed when user will call for suggested values for segment.

Signature

  • Its type is not specified.

$acceptValues

Here you should explain which values are accepted/useful for your segment, for example: "1, 2, 3, etc." or "comcast.net, proxad.net, etc.".

If the value needs any special encoding you should mention this as well. For example "Any URL including protocol. The URL must be URL encoded."

Signature

  • Its type is not specified.

$sqlSegment

Defines to which column in the MySQL database the segment belongs (if one is conifugred).

Defaults to $this.dbTableName . '.'. $this.columnName but you can customize it eg like HOUR(log_visit.visit_last_action_time).

Signature

  • Its type is not specified.

$sqlFilter

Interesting when specifying a segment.

Sometimes you want users to set segment values that differ from the way they are actually stored. For instance if you want to allow to filter by any URL than you might have to resolve this URL to an action id. Or a country name maybe has to be mapped to a 2 letter country code. You can do this by specifing either a callable such as array('Classname', 'methodName') or by passing a closure. There will be four values passed to the given closure or callable: string $valueToMatch, string $segment (see setSegment()), string $matchType (eg SegmentExpression::MATCH_EQUAL or any other match constant of this class) and $segmentName.

If the closure returns NULL, then Piwik assumes the segment sub-string will not match any visitor.

Signature

  • Its type is not specified.

$sqlFilterValue

Similar to $sqlFilter you can map a given segment value to another value.

For instance you could map "new" to 0, 'returning' to 1 and any other value to '2'. You can either define a callable or a closure. There will be only one value passed to the closure or callable which contains the value a user has set for this segment.

Signature

  • Its type is not specified.

$allowAnonymous

Defines whether this dimension (and segment based on this dimension) is available to anonymous users.

Signature

  • Its type is not specified.

$dbTableName

The name of the database table this dimension refers to

Signature

  • It is a string value.

$metricId

By default the metricId is automatically generated based on the dimensionId.

This might sometimes not be as readable and quite long. If you want more expressive metric names like nb_visits compared to nb_corehomevisitid, you can eg set a metricId visit.

Signature

  • Its type is not specified.

Methods

The abstract class defines the following methods:

getDbColumnJoin()

To be implemented when a column references another column

Signature

  • It does not return anything.

getDbDiscriminator()

Signature

  • It does not return anything.

getEnumColumnValues()

To be implemented when a column represents an enum.

Signature

  • It does not return anything.

getMetricId()

Get the metricId which is used to generate metric names based on this dimension.

Signature

  • It returns a string value.

install()

Installs the action dimension in case it is not installed yet.

The installation is already implemented based on the $columnName and $columnType. If you want to perform additional actions beside adding the column to the database - for instance adding an index - you can overwrite this method. We recommend to call this parent method to get the minimum required actions and then add further custom actions since this makes sure the column will be installed correctly. We also recommend to change the default install behavior only if really needed. FYI: We do not directly execute those alter table statements here as we group them together with several other alter table statements do execute those changes in one step which results in a faster installation. The column will be added to the log_link_visit_action MySQL table.

Example: ``` public function install() { $changes = parent::install(); $changes['log_link_visit_action'][] = "ADD INDEX index_idsite_servertime ( idsite, server_time )";

return $changes; } ```

Signature

  • Returns: array — An array containing the table name as key and an array of MySQL alter table statements that should be executed on the given table. Example: array( 'log_link_visit_action' => array("ADD COLUMN `$this->columnName` $this->columnType", "ADD INDEX ...") );

uninstall()

Uninstalls the dimension if a $columnName and columnType is set.

In case you perform any custom actions during install() - for instance adding an index - you should make sure to undo those actions by overwriting this method. Make sure to call this parent method to make sure the uninstallation of the column will be done.

Signature

  • It does not return anything.
  • It throws one of the following exceptions:

getCategoryId()

Returns the ID of the category (typically a translation key).

Signature

  • It returns a string value.

getName()

Returns the translated name of this dimension which is typically in singular.

Signature

  • It returns a string value.

getNamePlural()

Returns a translated name in plural for this dimension.

Signature

  • It does not return anything.

isAnonymousAllowed()

Defines whether an anonymous user is allowed to view this dimension

Signature

  • It does not return anything.

setSqlSegment()

Sets (overwrites) the SQL segment

Signature

  • It accepts the following parameter(s):

    • $segment (Piwik\Columns\$segment) —
  • It does not return anything.

setType()

Sets (overwrites the dimension type)

Signature

  • It accepts the following parameter(s):

    • $type (Piwik\Columns\$type) —
  • It does not return anything.

groupValue()

A dimension should group values by using this method.

Otherwise the same row may appear several times.

Signature

  • It accepts the following parameter(s):

    • $value (mixed) —

    • $idSite (int) —

  • It does not return anything.

formatValue()

Formats the dimension value.

By default, the dimension is formatted based on the set dimension type.

Signature

  • It accepts the following parameter(s):

    • $value (mixed) —

    • $idSite (int) —

    • $formatter (Formatter) —

  • It does not return anything.

configureMetrics()

Configures metrics for this dimension.

For certain dimension types, some metrics will be added automatically.

Signature

addSegment()

Adds a new segment.

It automatically sets the SQL segment depending on the column name in case none is set already.

See Also

  • \Piwik\Columns\Dimension::addSegment()

Signature

  • It accepts the following parameter(s):

  • It does not return anything.

getSegmentName()

Returns the name of the segment that this dimension defines

Signature

  • It does not return anything.

getSqlSegment()

Returns a sql segment expression for this dimension.

Signature

  • It does not return anything.

getDbTableName()

Returns the name of the database table this dimension belongs to.

Signature

  • It does not return anything.

getId()

Returns a unique string ID for this dimension.

The ID is built using the namespaced class name of the dimension, but is modified to be more human readable.

Signature

  • Returns: string — eg, "Referrers.Keywords"
  • It throws one of the following exceptions:
    • Exception — if the plugin and simple class name of this instance cannot be determined. This would only happen if the dimension is located in the wrong directory.

getAllDimensions()

Gets an instance of all available visit, action and conversion dimension.

Signature

getDimensions()

Signature

  • It accepts the following parameter(s):

  • It does not return anything.

factory()

Creates a Dimension instance from a string ID (see getId()).

Signature

  • It accepts the following parameter(s):

    • $dimensionId (string) — See getId().
  • Returns: Dimension|null — The created instance or null if there is no Dimension for $dimensionId or if the plugin that contains the Dimension is not loaded.

getModule()

Returns the name of the plugin that contains this Dimension.

Signature

  • It returns a string value.
  • It throws one of the following exceptions:
    • Exception — if the Dimension is not located within a Plugin module.

getType()

Returns the type of the dimension which defines what kind of value this dimension stores.

Signature

  • It does not return anything.

onEcommerceOrderConversion()

This event is triggered when an ecommerce order is converted.

Any returned value will be persist in the database. Return boolean false if you do not want to change the value in some cases.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) —

    • $visitor (Piwik\Tracker\Visitor) —

    • $action (Piwik\Tracker\Action|null) —

    • $goalManager (Piwik\Tracker\GoalManager) —

  • Returns: mixed|Piwik\Plugin\Dimension\false

onEcommerceCartUpdateConversion()

This event is triggered when an ecommerce cart update is converted.

Any returned value will be persist in the database. Return boolean false if you do not want to change the value in some cases.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) —

    • $visitor (Piwik\Tracker\Visitor) —

    • $action (Piwik\Tracker\Action|null) —

    • $goalManager (Piwik\Tracker\GoalManager) —

  • Returns: mixed|Piwik\Plugin\Dimension\false

onGoalConversion()

This event is triggered when an any custom goal is converted.

Any returned value will be persist in the database. Return boolean false if you do not want to change the value in some cases.

Signature

  • It accepts the following parameter(s):

    • $request (Piwik\Tracker\Request) —

    • $visitor (Piwik\Tracker\Visitor) —

    • $action (Piwik\Tracker\Action|null) —

    • $goalManager (Piwik\Tracker\GoalManager) —

  • Returns: mixed|Piwik\Plugin\Dimension\false