Add possibility to manage and view Apps

[tsteur]

This would be the first step to get #4734 done. The idea is to add only one new type "App" (or "Mobile App") for now (it might be useful to directly add another one such as "API"). It is more like an experiment to make some first experiences with this topic.

Features:

• We will modify the SitesManager so that users can select what type they want to create (Website, App or API)
  • Keep in mind an App does not have a URL, maybe optional an App ID eg org.piwik.mobile (probably not needed). An API would maybe rather have an "Endpoint" instead of a URL.
  • Note: As this here is pretty straight forward and most likely won't be a possible showstopper we could just add a column (eg "type") in the site table instead and set the type manually as a first step
• Provide a different default Dashboard for Apps as other things are important there, eg Devices
  • TBD: What if someone has already configured a dashboard, a Website related dashboard won't be so much useful for an App dashboard. We could ignore this problem in the beginning
• If possible we would use the term "Screens" instead of "Pageviews", "Users" instead of "Visitors" and "Sessions" instead of "Visits". Meaning we want to be able to rename metrics and metrics documentation. FYI: We had this topic in the past to rename it in general but we don't have to do this for now. In other "types" one has maybe "Workouts" instead of "Screens" etc. So we probably need a possibility to rename this anyway.
  • Note: In the first step we do maybe not care if Segments still says "Visits" etc
• Use the term "App" instead of "Website" everywhere eg in Email reports (from Email Reports #5333), etc
• OPTIONAL: Would we have to rename "Websites" as in "All Websites", "Website chooser" and "Sites Manager"? There is not really a good name for this I reckon? :( I think other name it like "Accounts", "Entities" or "Properties" but do not really like any of those

Some tasks to solve those tasks:

• Report classes should not be instantiated directly Report classes should not be instantiated directly #7821
• Provide an API for plugins to display (multiple) reports in a page Provide an API for plugins to display (multiple) reports in a page #7822
  • Change Widgets API for plugins Change Widgets API for plugins #7861
• Work always on one idSite in API methods Work always on one idSite in API.getReportMetadata #7834
• Not sure re order here
  • Let a type rename words "Website", "Site", "Websites" and "Sites" Let a type rename words "Website", "Site", "Websites" and "Sites" #7833 &
  • Provide a way for a type to rename any report and to disable/enable reports Provide a way for a type to rename any report and to disable/enable reports #7823
  • Add possibility to rename metrics based on the type of the site Add possibility to rename metrics based on the type of the site #7824
• Use generic wording whenever possible Use generic wording whenever possible #7826

I think this would be enough for a first step and will already provide a value for our users. We will already face enough challenges during this and learn a lot about possible problems. In the following step we could maybe disable / enable some reports depending on the type. We should create a follow up issue for Piwik 2.13.0 after this issue is resolved. The follow up issue will depend on how much of this issue we will get done in 2.12.0 etc

We will develop this in a way that plugins will be directly able to define their own "Types" even though this won't be a public API or whatever for a long time. New types should be already developed in a plugin. The types "App" and "API" would be most likely removed in the releases as it will be experimental and probably not yet ready for end-users. I think it won't even make sense to put them on the Marketplace unless we think the API is already stable enough.

Maybe it could be by default as easy (from a plugin developer perspective) as something like this:

{
 type: "app", 
 name: "App",  // or "PluginName_App" for translations
 namePlural:"Apps" // or name: {singular: "App", plural: "Apps"}
 manageFields: [{name: "AppId"...} ...], 
 dashboards: [{...}], 
 metrics: {"nb_visitors": "Users"...}, 
// menu: []
// reports: []
}

[mattab]

This feature is rather large scope and un-clear how it will be done. But let's try to think about this. User story: as a developer I want to define a custom type (eg. Mobile App) and for properties of my custom type I want to:

• Rename metrics (eg. we rename Visits to Sessions, Visitors to Users, Pageviews to Screens)
• Rename reports / menus / widgets (eg. we rename Visitor location (city) into User location (city))
• Remove reports (eg. Browser plugins report or Referrers reports do not apply to mobile app)
• Add reports (eg. for Mobile App or App we could later provide Errors/Exceptions reports Errors and Exceptions tracking of sites & apps #7544)
• ?

see for inspiration: Facebook Analytics for apps real time demo

[tsteur]

To implement this feature we will need to work on things that we want to achieve mid/long term anyway. Eg having everything based on APIs, render things in the UI, refactor the Archiver for easy additions of new reports, clarify what is in core and what in plugins, make sure a plugin does not do things that should be in another plugin (eg Live plugin has knowledge of all other plugins, the Report class in core knows about GoalMetrics but Goals are kinda a plugin), ...

I will use here the word "Type", this is the same as "Property" or whatever we will name it later.

Reports (Widgets, Menus, ...)

• We will most likely only support this for reports defined by a Report class, not for any Reports added via an event. We need to deprecate several events like API.getReportMetadata
• A report defines not only a "Name" but under circumstances also a "MenuTitle" and "WidgetTitle". They can all be different. Does this mean we'd have to provide up to 3 translations for each report? Again, we should better make use of %s.
• In a later version it should be possible that a type can disable certain metrics and dimensions. Eg if a page_url is disabled, the related report "Pages" would not be displayed, some metrics based on this would not be displayed as well.
• If someone renames eg the "Pages" report to "Screens", the API method will be still getPageUrls. We might allow some aliases in the future though. Eg getScreenNames. Actually: This is not really needed and adds unneeded complexity. Instead we should use generic wording here in API methods long term. To stay BC we might use aliases.

Dimensions / metrics

• Some metric names and documentation are accessed directly which is problematic eg https://github.com/piwik/piwik/blob/2.13.0-rc2/plugins/VisitsSummary/Controller.php#L64 We should refactor those kinda things and no longer translate them hardcoded.
• We might need to refactor the Metrics class https://github.com/piwik/piwik/blob/2.13.0-rc2/core/Metrics.php#L26 into many tiny classes and only access them via those classes. Metrics is marked as @api so BC might be an issue.
• It might make sense how the "Archiver" and "Report" etc definition might look like in the future for easy report definition. It might be easier to work on this first and add possibility of renaming metrics/dimensions afterwards.

Rename "website" wording

If we use the word "website" or "site" somewhere, we should replace it with "App", "Mobile App", "Server", ...

See #7833

Admin Websites UI

See #7893

Tracking

• Eg the tracker checks for "Site URLs" and performs a redirect under circumstances (when content tracking feature is used). "Mobile Apps" do not have URL's and such a redirect should not be performed. We might check / verify URL's in other places as well. Here we need to check where URLs are used and how we can handle them in the future.

In general

• If we create a new type "Mobile App", we should be aware that this can be a "Mobile Web Application" (running in a browser) or a "Native Mobile App" (running on eg Android / iOS). Here we need at some point to think about whether we want to differentiate between them. This can be decided rather late and is unimportant for now. Eg a "Mobile Web Application" can be still treated as a "Website" I reckon. Defining a new type will be easy later.
• This feature won't make it into Piwik 2.* so PHP 5.4 can be used from the beginning
• What happens if there are eg Mobile Apps created and one wants to disable Mobile Apps plugin? => We would only fallback to the generic wording / reports etc.

Example definition of a type

This is very early work in progress. I think in the beginning we would only support defining a type in PHP but for simple types we could also allow a JSON definition this will be easy to develop if needed.

• I wrote here eg "Mobile App". In reality this would be a translation key so that it can be translated. Eg
  private $name = 'TypeMobileApp_TypeName';
• By using PHP for this instead of JSON types can extend other types, types can apply custom behavior on when to disable a certain report etc.

class Type
{
    private $type = 'mobileapp';
    private $name = 'Mobile App';
    private $namePlural = 'Mobile Apps';
    private $management = array(
        'name'         => 'App name',
        'urls'         => 'App identifiers',
        'customFields' => array()
    );
    private $reports = array(
        'disable' => array('Referrers', 'DevicesDetection.getBrowser*'),
        'enable'  => array(),
        'rename'   => array(
            'VisitorInterest.getNumberOfVisitsByDaysSinceLast' => 'Sessions by days since last session'
        )
    );
    private $metrics = array(
        'nb_visitors' => 'Users',
        'nb_visitor' => 'User',
        'nb_unique_visitors' => 'Unique Users',
        'nb_visits' => 'Sessions',
        'nb_pageviews' => 'Screens'
    );
}

Part of our long term vision
This should be a separate wiki page but writing it here for now as it maybe helps understanding some things. Eg "Types", "Reports", "Metrics", "Dimensions" is something we want plugins to define / customize. Therefore we should kinda solve eg the problem of disabling/enabling reports in core and not in API.getProcessedReport/getReportMetadata.

• We want to separate the backend from the frontend and render everything on the client side. The frontend calls the Piwik HTTP API to get any data it needs.
• Everything is based on APIs
• We want plugins to define:
  • Reports (includes tracking new data etc)
    • Dimensions
      • Segments
    • Metrics
  • Visualizations
  • Import 3rd data (eg from Google Play, Weather information, ... etc.)
  • Widgets
  • Custom pages
  • Scheduled Tasks
  • Commands
  • Types / Properties, eg MobileApp, Server, ...
  • API methods (for exporting custom data etc)

Those things should be in core. Everything else on top should be in plugins.