Recherche avancée

Sur d’autres sites (5738)

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

• GDPR Compliance Checklist : A Detailed Walkthrough

  14 septembre 2023, par Erin — GDPR

  As digital transformation drives global economies, data has become a valuable currency to businesses of all shapes and sizes. As a result, the complex issue of data privacy is often in the spotlight.

  The General Data Protection Regulation (GDPR) is the key legal framework in the European Union to protect individual privacy and regulate business data handling. 

  Compliance with the GDPR is not just a legal mandate, it’s also good business. An 86% majority of users want more control over their data and 47% of users have switched providers over data privacy concerns.

  To help guide your business decisions around user privacy, this article will cover the key principles of GDPR, including a comprehensive GDPR compliance checklist.

  The key principles and requirements of GDPR

  Before we can translate GDPR’s objectives into practical steps, let’s begin with the defining features and key principles.

  GDPR : An overview

  The GDPR bolsters and unifies data protection standards for everyone within the EU. Enacted in 2018, it represented a seismic shift for companies and public authorities alike in protecting personal information. Its primary objective is to offer greater control to individuals over their data and to hold organisations accountable for its protection.

  GDPR establishes a legal framework that mandates corporate compliance with key principles to ensure user data security, transparency and choice. It sets the terms for your organisation’s privacy practices and the landscape of legal obligations you must navigate in data handling. 

  Key principles of GDPR

  There are seven core principles pivotal to GDPR compliance, which provide a roadmap for ethical and legal data practices.

  

  • Lawfulness, fairness and transparency : This principle demands lawful and fair processing of personal data. Companies should be transparent about their data processing activities, providing clear information in an accessible form.
  • Purpose limitation : Personal data should be collected for explicit, legitimate purposes and not further processed in a way incompatible with those purposes. This demands careful planning of data processing activities.
  • Data minimisation : Companies should only collect personal data that are necessary for their specified purposes, as anything more than this is illegal. This principle emphasises the importance of limiting scope, rather than performing blanket data collection.
  • Accuracy : This principle calls for maintaining data that is accurate, up-to-date and not misleading. Regular internal audits and updates are crucial to following this principle.
  • Storage limitation : Personal data should only be kept for as long as necessary for the purposes for which it was collected. This underscores the need for a detailed retention policy in your GDPR compliance efforts.
  • Integrity and confidentiality : Companies should protect personal data from unauthorised or unlawful processing and accidental loss or damage. Your organisation’s technical security measures play a vital role in this.
  • Accountability : Organisations should be able to demonstrate their compliance with GDPR principles. This underscores the importance of records of processing activities and regular audits as part of your compliance checklist.

  The importance of GDPR compliance for businesses

  Embracing GDPR compliance isn’t merely a matter of avoiding penalties — it’s a commitment to principles that reflect integrity, transparency and respect for personal data. At Matomo, we champion these principles, empowering companies with powerful and compliant web analytics. We make the compliance journey accessible and straightforward, making sure website analytics aligns with legal obligations and ethical practices.

  The implications of non-compliance

  It’s easy to highlight the dramatic fines imposed on tech giants such as Google and Meta. However, it’s essential to recognise that GDPR compliance extends to all companies, including small businesses — for whom even smaller fines can have a significant impact.

  The implications of non-compliance aren’t limited to financial penalties alone, either. Failing to meet obligations can tarnish reputations, erode trust and hinder business activities. Non-compliance could lead to a breach of privacy policy, causing a ripple effect that may be challenging to overcome.

  The potential benefits of being GDPR compliant

  Adhering to GDPR regulations is more than a checkbox on a form — it’s a comprehensive approach to handling personal data responsibly. It fosters trust, opens doors to European customers and builds enduring relationships with individuals whose rights are protected. In fulfilling these obligations and practices, businesses not only meet legal requirements but also foster a culture of ethical conduct and business success.

  Comprehensive GDPR compliance checklist

  Ensuring GDPR compliance may seem like a complex task, but this detailed checklist will simplify your journey. From consent management to data security, we’ve got you covered.

  

  Establish personal data collection and consent management

  When it comes to GDPR compliance, not all consent is created equal. Two distinct forms exist : explicit consent and implied consent. But what exactly sets them apart, and why does it matter to your organisational measures ?

  Explicit consent from users means that the individual has unequivocally agreed to the processing of personal data. It’s an unambiguous agreement, often obtained through a deliberate action like ticking a box. Details are paramount, as the person giving consent must be fully informed about the processing activities.

  • Inform clearly : Use plain language to explain how data will be used and be transparent about processing practices.
  • Obtain active agreement : Use forms or checkboxes (not pre-ticked boxes) to ensure active participation and that you are obtaining explicit user consent.
  • Document it : Keep records of consent, including when and how it was obtained, as a crucial part of your compliance efforts.
  • Facilitate withdrawal : Use consent mechanisms that allow for easy withdrawal of consent for users who decide to opt out.
  • Manage consent forms : Tools like Matomo’s Consent Management Platform can provide accessible forms that not only enhance transparency but also empower individuals, allowing them to feel in control of their details and rights.

  Facilitate data subject rights and access requests

  GDPR emphasises individual rights by empowering users with control over their personal data processing. Here’s a succinct breakdown :

  • Know the rights of individuals : GDPR outlines individual rights such as data access, error rectification, erasure and data portability, allowing individuals to guide how their details are used, processed or shared.
  • Simplify complying with access requests : Companies must respond to access requests efficiently, usually within one month, without undue delay, reflecting organisational measures of respect.
  • Employ ethical and compliant digital analytics : As a leader in ethical web analytics, Matomo subtly aids in compliance efforts, protecting privacy without compromising functionality.

  These practices align with a modern understanding of privacy, emphasising more than legal obligations. By employing Matomo, companies simplify the processing of access requests, which fosters transparency and user control over personal data.

  Implement clear data privacy practices

  Data privacy and consent mechanisms are key tools for compliance. Crafting a comprehensive privacy policy helps protect individuals’ rights and provides integrity in personal data processing. Designing sites and applications with data protection in mind ensures your compliance from the ground-up.

  • Create an easy to understand privacy policy : Create a clear, GDPR-compliant privacy policy that details processing activities, storage limitations and organisational measures, all in plain language. 

  By implementing these steps, companies not only adhere to their legal obligations but also foster an inclusive community that values privacy and ethics. Whether you’re an IT professional or marketer, Matomo’s platform can guide you through the maze of GDPR complexities, inspiring positive change towards responsible data handling.

  Implement data storage limitations and robust security

  Data storage and security are foundational elements of compliance efforts. Companies must foster a proactive approach to preventing data breaches by understanding potential cyberthreats and enforcing appropriate security controls across applications and infrastructures.

  

  • Implement storage limitations : Define limitations on time and scope to avert undue retention and protect personal details.
  • Embrace technical security : Utilise secure processes like encryption, access controls, firewalls and so on, bolstering protection by design.
  • Establish a comprehensive security policy : Align security practices with privacy laws and regulations, including GDPR.
  • React swiftly to personal data breaches : A security breach requires an immediate response, without undue delay, to honour legal obligations and maintain customer trust. Develop a plan for notifying supervisory authorities and affected individuals promptly in the event of a personal data breach.

  Security measures for personal data are about more than just fulfilling legal obligations — they’re about building a safe and ethical digital ecosystem that instils confidence in customers.

  Keep cross-border data transfers in mind

  Cross-border data transfers present a unique challenge, with increased complexity due to varying data privacy laws across regions. You must understand the respective regulations of participating countries and align your compliance practices appropriately to respect all that are relevant to your organisation. 

  For example, data privacy laws in the US are generally more lax than the GDPR so US companies taking on EU customers must hold themselves to a higher standard, with stricter controls placed on their data processing practices.

  • Evaluate third-party services : For companies utilising global networks of third-party services, be sure to select providers that maintain ongoing knowledge and vigilance towards privacy law compliance. Platforms like Matomo that innately prioritise transparency and privacy, have implemented robust security measures, and document transfers diligently are worth considering. 

  Conduct internal audits and compliance checks

  Compliance is not a “one and done” setup, but an ongoing journey requiring regular internal audits. Systems settings can drift over time, and datasets can become increasingly complex as companies scale. Human error happens, too. Audits identify gaps in your compliance efforts to guide actionable improvements. 

  • Conduct regular audits : Stay proactive with internal audits and systematic monitoring, adapting policies to align with privacy laws. Clarity in privacy notices and cookie banners fosters confidence, while regular assessments ensure alignment with GDPR requirements.
  • Ensure transparency : Platforms like Matomo simplify audits, offering valuable insights and support for ethical web analytics and transparency. The right platform can increase visibility and make generating your reports easier. Integrating these processes guarantees GDPR-aligned measures while emphasising data ownership and customer-centric values.
  • Educate and train staff : Engage in ongoing staff education and training on GDPR compliance, privacy policies, and their related responsibilities.

  

  Case study : GDPR compliance in action

  Achieving compliance with the General Data Protection Regulation (GDPR) stands as a paramount concern for businesses worldwide. Both small and large companies have embarked on this journey, implementing measures and revising privacy policies to conform to these regulations.

  Typeform

  Based in Ireland, Typeform, a company dealing with online forms, took GDPR compliance very seriously. Here’s how they achieved it :

  1. Conducting a data protection impact assessment (DPIA) : This vital step helped them assess personal data breach risks and enabled systematic monitoring of potential challenges.
  2. Implementing technical and organisational measures : Security measures such as encryption, access control and drafting a security policy reinforced their personal data processing mechanisms.
  3. Revamping privacy policy : They transformed their privacy policy with accessible, plain language, making it clear and user-friendly.
  4. Appointing a data protection officer (DPO) : This aligned with their core activities and strengthened their compliance efforts.

  The benefits for Typeform were profound :

  • Enhanced customer trust and confidence
  • Reduced risk of fines and penalties
  • Bolstered data security and privacy
  • Improved brand reputation, positioning them favourably among European customers

  Ensuring GDPR Compliance with Matomo Analytics

  Matomo is more than just an analytics platform ; it is a trusted guide in the realm of data privacy. Our mission is to empower users with full data ownership, fostering an inclusive digital community built on trust and transparency. Our suite of features has been meticulously designed to align with GDPR regulations, ensuring that businesses can navigate the complexities of compliance with ease and confidence.

  1. Data Anonymisation

  Matomo’s focus on ethical digital analytics means the platform allows for the anonymisation of user data, ensuring that individual identities remain protected.

  2. Robust GDPR Management

  Beyond just a GDPR Manager, Matomo provides an encompassing framework to streamline compliance activities. From managing user consent to meticulous record-keeping of processing activities, Matomo ensures you are always a step ahead.

  3. User Empowerment with Opt-Out Capabilities

  Matomo respects user choices. The platform offers users an easy way to opt-out of all tracking, giving them control over their data.

  4. First-party Cookies as the Standard

  By using first-party cookies by default, Matomo ensures data remains with the website owner, minimising potential breaches or misuse.

  5. Transparent Data Collection Practices

  Users have the right to know their data. With Matomo, they can view the exact data being collected, reinforcing a transparent relationship between businesses and their users.

  6. Visitor Data Management

  Upon request, Matomo offers capabilities to delete visitor data, aligning with the GDPR’s right to be forgotten.

  7. Data Ownership and Privacy Assurance

  Unlike other web analytics platforms, with Matomo, you retain full ownership of your data and can rest assured that it is not being used for other purposes such as advertising.

  8. IP Anonymisation

  Protecting user location details, Matomo anonymises IP addresses, adding an additional layer of privacy.

  9. Customisable Data Visualisation

  Recognising that not all data is essential, Matomo allows the disabling of visitor logs and profiles, giving businesses the flexibility to decide what data they track.

  By taking a holistic approach to GDPR compliance, Matomo streamlines the processes for you and ensures you follow the legal and ethical best practices.

  

  Start your GDPR compliance journey today

  The global focus on data privacy requires using a GDPR compliance checklist. With 137 countries implementing data protection laws (UN), companies must align with international standards. Compliance, after all, goes beyond avoiding breaches— it’s about upholding privacy and building trust.

  As your trusted guide, Matomo invites you on this GDPR journey. With us, you’ll uphold privacy obligations and manage your processing activities effectively. Compliance isn’t a one-time task but a continuous journey to enhance practices and align with individual rights. Start this vital journey with Matomo today. Try it free for 21-days. No credit card required.

  Disclaimer

  We are not lawyers and don’t claim to be. The information provided here is to help give an introduction to GDPR. We encourage every business and website to take data privacy seriously and discuss these issues with your lawyer if you have any concerns.