Click here if you want to read this article for the latest Piwik version

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.

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

$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.

Methods

The abstract class defines the following methods:

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.

getName()

Get the translated name of the dimension.

Defaults to an empty string.

Signature

  • It returns a string value.

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.

install()

Installs the conversion 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_conversion MySQL table.

Example: ``` public function install() { $changes = parent::install(); $changes['log_conversion'][] = "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_conversion' => 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:

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