Recherche avancée

Sur d’autres sites (5503)

• How to expose new API methods in the HTTP Reporting API – Introducing the Piwik Platform

  26 février 2015, par Thomas Steur — Development

  This is the next post of our blog series where we introduce the capabilities of the Piwik platform (our previous post was How to write UI tests for your plugin). This time you’ll learn how to extend our Reporting API. For this tutorial you will need to have basic knowledge of PHP.

  What is Piwik’s Reporting API ?

  It allows third party applications to access analytics data and manipulate miscellaneous data (such as users or websites) through HTTP requests.

  What is it good for ?

  The Reporting API is used by the Piwik UI to render reports, to manage users, and more. If you want to add a feature to the Piwik UI, you might have to expose a method in the API to access this data. As the API is called via HTTP it allows you to fetch or manipulate any Piwik related data from anywhere. In these exposed API methods you can do pretty much anything you want, for example :

  • Enhance existing reports with additional data
  • Filter existing reports based on custom rules
  • Access the database and generate custom reports
  • Persist and read any data
  • Request server information

  Getting started

  In this series of posts, we assume that you have already set up your development environment. If not, visit the Piwik Developer Zone where you’ll find the tutorial Setting up Piwik.

  To summarize the things you have to do to get setup :

  • Install Piwik (for instance via git).
  • Activate the developer mode : ./console development:enable.
  • Generate a plugin : ./console generate:plugin --name="MyApiPlugin". There should now be a folder plugins/MyApiPlugin.
  • And activate the created plugin : ./console plugin:activate "MyApiPlugin"

  Let’s start creating an API

  We start by using the Piwik Console to create a new API :

  ./console generate:api

  The command will ask you to enter the name of the plugin the created API should belong to. I will simply use the above chosen plugin name “MyApiPlugin”. There should now be a file plugins/MyApiPlugin/API.php which contains already an example to get you started easily :

  class API extends \Piwik\Plugin\API
  {
      public function getAnswerToLife($truth = true)
      {
          if ($truth) {
              return 42;
          }
   
          return 24;
      }
   
      public function getExampleReport($idSite, $period, $date, $wonderful = false)
      {
          $table = DataTable::makeFromSimpleArray(array(
              array('label' => 'My Label 1', 'nb_visits' => '1'),
              array('label' => 'My Label 2', 'nb_visits' => '5'),
          ));
   
          return $table;
      }
  }
  Télécharger

  Any public method in that file will be available via the Reporting API. For example the method getAnswerToLife can be called via this URL : index.php?module=API&method=MyApiPlugin.getAnswerToLife. The URL parameter method is a combination of your plugin name and the method name within this class.

  Passing parameters to your method

  Both example methods define some parameters. To pass any value to a parameter of your method simply specify them by name in the URL. For example ...&method=MyApiPlugin.getExampleReport&idSite=1&period=week&date=today&wonderful=1 to pass values to the parameters of the method getExampleReport.

  Returning a value

  In an API method you can return any boolean, number, string or array value. A resource or an object cannot be returned unless it implements the DataTableInterface such as DataTable (the primary data structure used to store analytics data in Piwik), DataTable\Map (stores a set of DataTables) and DataTable\Simple (a DataTable where every row has two columns : label and value).

  Did you know ? You can choose the response format of your API request by appending a parameter &format=JSON|XML|CSV|... to the URL. Check out the Reporting API Reference for more information.

  Best practices

  Check user permissions

  Do not forget to check whether a user actually has permissions to access data or to perform an action. If you’re not familiar with Piwik’s permissions and how to check them read our User Permission guide.

  Keep API methods small

  At Piwik we aim to write clean code. Therefore, we recommend to keep API methods small (separation of concerns). An API pretty much acts like a Controller :

  public function createLdapUser($idSite, $login, $password)
  {
      Piwik::checkUserHasAdminAccess($idSite);
      $this->checkLogin($login);
      $this->checkPassword($password);
      
      $myModel = new LdapModel();
      $success = $myModel->createUser($idSite, $login, $password);
      
      return $success;
  }
  Télécharger

  This is not only easy to read, it will also allow you to create simple tests for LdapModel (without having to bootstrap the whole Piwik layer) and you will be able to reuse it in other places if needed.

  Calling APIs of other plugins

  For example if you want to fetch an existing report from another plugin, say a list of all Page URLs, do not request this report by calling that method directly :

  \Piwik\Plugins\Actions\API::getInstance()->getPageUrls($idSite, $period, $date);

  . Instead, issue a new API request :

  $report = \Piwik\API\Request::processRequest('Actions.getPageUrls', array(
  
      'idSite' => $idSite,
  
      'period' => $period,
  
      'date'   => $date,
  
  ));

  This has several advantages :

  • It avoids a fatal error if the requested plugin is not available on a Piwik installation
  • Other plugins can extend the called API method via events (adding additional report data to a report, doing additional permission checks) but those events will be only triggered when requesting the report as suggested
  • If the method parameters change, your request will most likely still work

  Publishing your Plugin on the Marketplace

  In case you want to share your API with other Piwik users you can do this by pushing your plugin to a public GitHub repository and creating a tag. Easy as that. Read more about how to distribute a plugin and best practices when publishing a plugin.

  Isn’t it easy to create a API ? We never even created a file ! If you have any feedback regarding our APIs or our guides in the Developer Zone feel free to send it to us.

• How to expose new API methods in the HTTP Reporting API – Introducing the Piwik Platform

  26 février 2015, par Thomas Steur — Development

  This is the next post of our blog series where we introduce the capabilities of the Piwik platform (our previous post was How to write UI tests for your plugin). This time you’ll learn how to extend our Reporting API. For this tutorial you will need to have basic knowledge of PHP.

  What is Piwik’s Reporting API ?

  It allows third party applications to access analytics data and manipulate miscellaneous data (such as users or websites) through HTTP requests.

  What is it good for ?

  The Reporting API is used by the Piwik UI to render reports, to manage users, and more. If you want to add a feature to the Piwik UI, you might have to expose a method in the API to access this data. As the API is called via HTTP it allows you to fetch or manipulate any Piwik related data from anywhere. In these exposed API methods you can do pretty much anything you want, for example :

  • Enhance existing reports with additional data
  • Filter existing reports based on custom rules
  • Access the database and generate custom reports
  • Persist and read any data
  • Request server information

  Getting started

  In this series of posts, we assume that you have already set up your development environment. If not, visit the Piwik Developer Zone where you’ll find the tutorial Setting up Piwik.

  To summarize the things you have to do to get setup :

  • Install Piwik (for instance via git).
  • Activate the developer mode : ./console development:enable.
  • Generate a plugin : ./console generate:plugin --name="MyApiPlugin". There should now be a folder plugins/MyApiPlugin.
  • And activate the created plugin : ./console plugin:activate "MyApiPlugin"

  Let’s start creating an API

  We start by using the Piwik Console to create a new API :

  ./console generate:api

  The command will ask you to enter the name of the plugin the created API should belong to. I will simply use the above chosen plugin name “MyApiPlugin”. There should now be a file plugins/MyApiPlugin/API.php which contains already an example to get you started easily :

  class API extends \Piwik\Plugin\API
  {
      public function getAnswerToLife($truth = true)
      {
          if ($truth) {
              return 42;
          }
   
          return 24;
      }
   
      public function getExampleReport($idSite, $period, $date, $wonderful = false)
      {
          $table = DataTable::makeFromSimpleArray(array(
              array('label' => 'My Label 1', 'nb_visits' => '1'),
              array('label' => 'My Label 2', 'nb_visits' => '5'),
          ));
   
          return $table;
      }
  }
  Télécharger

  Any public method in that file will be available via the Reporting API. For example the method getAnswerToLife can be called via this URL : index.php?module=API&method=MyApiPlugin.getAnswerToLife. The URL parameter method is a combination of your plugin name and the method name within this class.

  Passing parameters to your method

  Both example methods define some parameters. To pass any value to a parameter of your method simply specify them by name in the URL. For example ...&method=MyApiPlugin.getExampleReport&idSite=1&period=week&date=today&wonderful=1 to pass values to the parameters of the method getExampleReport.

  Returning a value

  In an API method you can return any boolean, number, string or array value. A resource or an object cannot be returned unless it implements the DataTableInterface such as DataTable (the primary data structure used to store analytics data in Piwik), DataTable\Map (stores a set of DataTables) and DataTable\Simple (a DataTable where every row has two columns : label and value).

  Did you know ? You can choose the response format of your API request by appending a parameter &format=JSON|XML|CSV|... to the URL. Check out the Reporting API Reference for more information.

  Best practices

  Check user permissions

  Do not forget to check whether a user actually has permissions to access data or to perform an action. If you’re not familiar with Piwik’s permissions and how to check them read our User Permission guide.

  Keep API methods small

  At Piwik we aim to write clean code. Therefore, we recommend to keep API methods small (separation of concerns). An API pretty much acts like a Controller :

  public function createLdapUser($idSite, $login, $password)
  {
      Piwik::checkUserHasAdminAccess($idSite);
      $this->checkLogin($login);
      $this->checkPassword($password);
      
      $myModel = new LdapModel();
      $success = $myModel->createUser($idSite, $login, $password);
      
      return $success;
  }
  Télécharger

  This is not only easy to read, it will also allow you to create simple tests for LdapModel (without having to bootstrap the whole Piwik layer) and you will be able to reuse it in other places if needed.

  Calling APIs of other plugins

  For example if you want to fetch an existing report from another plugin, say a list of all Page URLs, do not request this report by calling that method directly :

  \Piwik\Plugins\Actions\API::getInstance()->getPageUrls($idSite, $period, $date);

  . Instead, issue a new API request :

  $report = \Piwik\API\Request::processRequest('Actions.getPageUrls', array(
  
      'idSite' => $idSite,
  
      'period' => $period,
  
      'date'   => $date,
  
  ));

  This has several advantages :

  • It avoids a fatal error if the requested plugin is not available on a Piwik installation
  • Other plugins can extend the called API method via events (adding additional report data to a report, doing additional permission checks) but those events will be only triggered when requesting the report as suggested
  • If the method parameters change, your request will most likely still work

  Publishing your Plugin on the Marketplace

  In case you want to share your API with other Piwik users you can do this by pushing your plugin to a public GitHub repository and creating a tag. Easy as that. Read more about how to distribute a plugin and best practices when publishing a plugin.

  Isn’t it easy to create a API ? We never even created a file ! If you have any feedback regarding our APIs or our guides in the Developer Zone feel free to send it to us.

• How you can use the Piwik AOM plugin to improve your data and make better online marketing decisions

  13 septembre 2017, par André Kolell — Plugins, AdWords, Bing, Case Study, Criteo, eccommerce tracking, Facebook Ads, how to install piwik analytics, how-to piwik, integration, piwik, Taboola

  Hi, this is André, one of the authors of the Piwik Advanced Online Marketing plugin, which has just hit 5,000 downloads on the Piwik marketplace. In this blog post I’ll show you how Piwik AOM improves your data and enables you to make better online marketing decisions.

  Piwik itself is excellent in tracking all kinds of visitor data, like where a visitor is coming from and what he’s doing on your page or app (pageviews, events, conversions). But what Piwik did not yet take a closer a look at, is how much you’ve invested into your marketing activities and how profitable they are.

  With the Piwik AOM plugin you can integrate data like advertising costs, advertising campaign names, ad impressions etc. from advertising platforms (such as Google AdWords, Microsoft Bing, Criteo, Facebook Ads and Taboola) and individual campaigns (such as such as cost per view/click/acquisition and fixed price per months deals) into Piwik and combine that data with individual Piwik visits.

  Piwik AOM adds a new marketing performance report to Piwik giving you a great overview of all your marketing activities with drill-down functionality :

  

   

  When taking a look at a specific visitor, Piwik AOM shows you the exact cost of acquiring a specific visit :

  

   

  Leveraging Piwik AOM’s full potential

  But although you can access Piwik AOM’s valuable data directly in the Piwik UI for ad-hoc analyses, Piwik AOM’s true strength comes into play when working with the raw data in an external business intelligence application of your choice, where you can further integrate Piwik AOM’s data with your most accurate backend data (like conversion’s contribution margins after returns, new vs. existing customer, etc.).

  Piwik AOM offers some API endpoints that allow you to fetch the data you need but you can also retrieve it directly from Piwik AOM’s aom_visits table, which includes all visits, all allocated advertising costs and advertising campaign details. As there is never data being deleted from aom_visits, the table can easily be connected to your ETL tool with its last update timestamp column. A third way to get data out of Piwik AOM is by developing your own Piwik plugin and listening to the AOM.aomVisitAddedOrUpdated event, which is posted whenever an aom_visits record is added or updated.

  Integrating Piwik AOM’s data with your backend data in the business intelligence application of your choice allows you to evaluate the real performance of your online marketing campaigns when applying different conversion attribution models, conduct customer journey analyses, create sophisticated forecasts and whatever you can think of.

  AOM Use case

  A company that followed this approach, is FINANZCHECK.de, one of Germany’s leading loan comparison websites. At the eMetrics summit 2016 in Berlin, Germany, I gave a talk about FINANZCHECK’s architectural online marketing setup. Until recently, FINANZCHECK used Pentaho data integration to integrate data from Piwik, Piwik AOM and additional internal tools like its proprietary CRM software into Jaspersoft, its data warehouse an BI solution. The enriched data in Jaspersoft was not only used for reporting to various stakeholders but also for optimising all kinds of marketing activities (e.g. bids for individual keywords in Google AdWords) and proactive alerting. Not long ago, FINANZCHECK started an initiative to improve its setup even further – I’ll hopefully be able to cover this in a more detailed case study soon.

  Roadmap

  In the past, we had the chance to make great progress in developing this plugin by solving specific requirements of different companies who use Piwik AOM. During the next months, we plan to integrate more advertising platforms, reimplement Facebook Ads, improve the support of individual campaigns and work on the general plugin stability and performance.

  Before you install Piwik AOM

  Before installing Piwik AOM, you should know that its initial setup and even its maintenance can be quite complex. Piwik AOM will heavily modify your Piwik installation and you will only benefit from Piwik AOM if you are willing to invest quite some time into it.

  If you are not familiar with Piwik’s internals, PHP, MySQL, database backups, cronjobs, creating API accounts at the advertising platforms or adding parameters to your advertising campaign’s URLs, you should probably not install it on your own (at least not in your production environment).

  Piwik AOM has successfully been tested with up to 25k visitors a day for a period of more than two years, running on an AWS server with 4 GB RAM, once CPU and a separate AWS RDS MySQL database.

  Ideas and Support

  If you have ideas for new features or need support with your Piwik AOM installation or leveraging your marketing data’s potential in general, feel free to get in touch with the plugin’s co-author Daniel or me. You can find our contact details on the plugin’s website http://www.advanced-online-marketing.com.

  How to get the Piwik AOM plugin ?

  The Piwik AOM plugin is freely available through the Piwik marketplace at https://plugins.piwik.org/AOM

  Did you like this article ? If yes do not hesitate to share it or give your feedback about the topic you would like us to write about.