Recherche avancée

Sur d’autres sites (5472)

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

• Dreamcast SD Adapter and DreamShell

  31 décembre 2014, par Multimedia Mike — Sega Dreamcast

  Nope ! I’m never going to let go of the Sega Dreamcast hacking. When I was playing around with Dreamcast hacking early last year, I became aware that there is such a thing as an SD card adapter for the DC that plugs into the port normally reserved for the odd DC link cable. Of course I wanted to see what I could do with it.

  The primary software that leverages the DC SD adapter is called DreamShell. Working with this adapter and the software requires some skill and guesswork. Searching for these topics tends to turn up results from various forums where people are trying to cargo-cult their way to solutions. I have a strange feeling that this post might become the unofficial English-language documentation on the matter.

  Use Cases
  What can you do with this thing ? Undoubtedly, the primary use is for backing up (ripping) the contents of GD-ROMs (the custom optical format used for the DC) and playing those backed up (ripped) copies. Presumably, users of this device leverage the latter use case more than the former, i.e., download ripped games, load them on the SD card, and launch them using DreamShell.

  However, there are other uses such as multimedia playback, system exploration, BIOS reprogramming, high-level programming, and probably a few other things I haven’t figured out yet.

  Delivery
  I put in an order via the dc-sd.com website and in about 2 short months, the item arrived from China. This marked my third lifetime delivery from China and curiously, all 3 of the shipments have pertained to the Sega Dreamcast.

  
  

  

  Click for larger image

  
  

  I thought it was very interesting that this adapter came in such complete packaging. The text is all in Chinese, though the back states “Windows 98 / ME / 2000 / XP, Mac OS 9.1, LINUX2.4”. That’s what tipped me off that they must have just cannibalized some old USB SD card readers and packaging in order to create these. Closer inspection of the internals through the translucent pink case confirms this.

  Usage
  According to its change log, DreamShell has been around for a long time with version 1.0.0 released in February of 2004. The current version is 4.0.0 RC3. There are several downloads available :

  1. DreamShell 4.0 RC 3 CDI Image
  2. DreamShell 4.0 RC 3 + Boot Loader
  3. DreamShell 4.0 RC 3 + Core CDI image

  Option #2 worked for me. It contains a CDI disc image and the DreamShell files in a directory named DS/.

  Burn the CDI to a CD-R in the normal way you would burn a bootable Dreamcast disc from a CDI image. This is open-ended and left as an exercise to the reader, since there are many procedures depending on platform. On Linux, I used a small script I found once called burncdi-dc.sh.

  Then, copy the contents of the DS/ folder to an SD card. As for filesystem, FAT16 and FAT32 are both known to work. The files in DS/ should land in the root of the SD card ; the folder DS/ should not be in the root.

  Plug the SD card into the DC SD adapter and plug the adapter in the link cable port on the back of the Dreamcast. Then, boot the disc. If it works, you will see this minor corruption of the usual Sega licensing screen :

  
  
  

  Then, there will be a brief white-on-black text screen that explains the booting process :
  

  
  
  

  Then, there will be the main DreamShell logo :

  
  
  

  Finally, you will land on the DreamShell main desktop :

  
  
  

  Skepticism
  At first, I was supremely skeptical of the idea that this SD adapter could perform speedily enough to play games reasonably. This was predicated on the observation that my DC coder’s cable that I used to use for homebrew development could not transfer faster than 115200 bits/second, amounting to about 11 kbytes/sec. I assumed that this was a fundamental limitation of the link port.

  In fact, I ripped a few of my Dreamcast discs over a decade ago and still have those rips lying around. So I copied the ISO image of Resident Evil : Code Veronica — the game I personally played most on the DC — to the SD card (anywhere works) and used the “ISO loader” icon seen on the desktop above to launch the game.

  It works :

  
  
  

  The opening FMV plays at full speed. Everything loads as fast as I remember. I was quite surprised.

  Digression : My assumptions about serial speeds have often been mistaken. 10 years ago, I heard stories about how we would soon be able to watch streaming video on our cell phones. I scoffed because I thought the 56K limitation of dialup modems was some sort of fundamental speed-of-light type of limitation for telephony bandwidth, wired or wireless.

  The desktop menu also includes a ‘speedtest’ tool that profiles the write and read performance of your preferred storage medium. For my fastest SD card (a PNY 2 GB card) :

  
  
  

  This is probably more representative of the true adapter bandwidth as reading and writing is a good deal faster through more modern interfaces on PC and Mac with this same card.

  Look at the other options on the speedtest console. Hard drive ? Apparently, it’s possible, but it requires a good deal more hardware hacking than just purchasing this SD adapter.

  Ripping
  As you can see from the Resident Evil screenshot, playing games works quite nicely. How about ripping ? I’m pleased to say that DreamShell has a beautiful ripping interface :

  
  
  

  Enter a name for the disc (or read the disc label), select the storage medium, and let it, well, rip. It indicates which track it’s working on and the Sega logo acts as a progress bar, shading blue as the track rip progresses.

  I’m finally, efficiently, archiving that collection of Sega Dreamcast demo discs ; I’m hoping they’ll eventually find a home at the Internet Archive. How is overall ripping performance ? Usually about 38-40 minutes to rip a full 900-1000 MB. That certainly beats the 27-28 hours that were required when I performed the ripping at 11 kbytes/sec via the DC coders cable.

  All is well until I get a sector reading error :

  
  
  

  That’s when it can come in handy to have 3 DC consoles (see ?! not crazy !).

  Other Uses
  There’s a file explorer. You can browse the filesystem of the SD card, visual memory unit, or the CD portion of the GD-ROM (would be more useful if it accessed the GD area). There are FFmpeg files included. So I threw a random Cinepak file and random MPEG-1 file at it to see what happens. MPEG-1 didn’t do anything, but this Cinepak file from some Sierra game played handily :

  
  
  

  If you must enter strings, it helps to have a Dreamcast keyboard (which I do). Failing that, here’s a glimpse of the onscreen keyboard that DreamShell equips :

  
  
  

  Learning to use it is a game in itself.

  There is an option of installing DreamShell in the BIOS. I did not attempt this. I don’t know if it’s possible (not like there’s a lot of documentation)– perhaps a custom BIOS modchip is needed. But here’s what the screen looks like :

  
  
  

  There is also a plain console to interact with (better have a physical keyboard). There are numerous file manipulation commands and custom system interaction commands. I see one interesting command called ‘addr’ that looks useful for dumping memory regions to a file.

  A Lua language interpreter is also built in. I would love to play with this if I could ascertain whether DreamShell provided Dreamcast-specific APIs.

  Tips And Troubleshooting
  I have 3 Dreamcast consoles, affectionately named Terran, Protoss, and Zerg after the StarCraft II stickers with which they are adorned. Some seem to work better than others. Protoss seemed to be able to boot the DreamShell disc more reliably than the others. However, I was alarmed when it couldn’t boot one morning when it was churning the previous day.

  I think the problem is that it was just cold. That seemed to be the issue. I put in a normal GD-ROM and let it warm up on that disc for awhile and then DreamShell booted fine. So that’s my piece of cargo-culting troubleshooting advice.