The idea is to send reports via SMS using online SMS providers. Users need to provide one or several phone numbers and a SMS authorization token.
Reports
So far, we have identified three different kinds of reports. Here are the candidate templates :
- Standard Report for 1 website:
from=Report Virtual-drums.com Daily
text=Yesterday, 150 visits (+15%), 555 pages (+22%), Goals: X conversions (-XX%), Revenue: xx€ (-xx%).
from=Report Virtual-drums.com Daily
text=Yesterday (Jan 21st): virtual-drums.com: 150 visits (+15%), 555 pages (+22%), Goals: X conversions (-XX%), Revenue: xx€ (-xx%). forum.piwik.org: 600 visits (-12%), 32 pages (+2%), mamamia.fr: 330 visits (+1%), 555 pages (+22%), Ecommerce Revenue: 34$ (-60%) from 45 orders (+111%)
- Information displayed for all websites: Visits, Pages
- Information displayed for all websites that have at least one conversion: Conversions, Revenue (if Revenue > 0)
- Information displayed for all website with Ecommerce enabled: Orders, Revenue
- API to use:
- When “All Websites” report is selected: The API MultiSites.getAll can be used for these reports
- It needs to be enhanced to also return the number of Conversions, and Ecommerce orders.
- To not add overhead for the “All websites” dashboard, maybe we could add a new parameter to MultiSites.getAll called “enhanced”, 0 by default. When enhanced==1, we would enrich the returning data with Conversions/Ecommerce orders?
- When only “Standard summary report” is selected: Could we also use the MultiSites API, but implement it so it works for one website only?
- The advantage of using this API is that it already returns the % evolution so that the SMS reports would not have to process any data
- the implementation code for a new MultiSites.get could be shared with the existing MultiSites.getAll
Desirable features
- The periodicity of SMS reports is configurable the same way as for HTML and PDF reports.
- SMS reports can be downloaded for preview the same way as for HTML and PDF reports.
SMS Authorization Token and Account Management
Online SMS providers with open APIs provide a SMS authorization token to registered users.
Within Piwik, this token will be manageable one of two ways :
- One token by Piwik instance
In this case, it is the responsibility of the super user to provide the token in the SMS management user interface.
It is the only user who has the right to consult the number of remaining credits.
In this case, it is the responsibility of each user to provide the token.
Each user has access to the number of remaining credits.
–
Deciding between the two modes of management is done by the super user with the following options in the SMS management UI :
- (x) Allow other users to create and manage their own SMS account.
- ( ) Allow users with ‘view’ or ‘admin’ access to send SMS reports using your SMS credit.
The second option is the default.
–
When a token is typed-in by the user, a call to the SMS API will be performed to validate the token and display the amount of remaining credit. The token will not be stored if it can’t be validated.
The user will have the ability to display the number of remaining credits in the SMS management pages. A message will be displayed in the report and SMS management pages when no credit are left in the account.
The token can not be modified. To change an already validated token the user will have to remove it and add a new one.
–
If the token is not provided
- In the SMS management page
When the token is managed by the super user and a standard user accesses the SMS management page, display “SMS reports are not properly configured, please contact your administrator”.
Phone Number
Within the SMS management UI, each user can manage one or several phone numbers. A phone number will be selectable within the report creation and edition forms only if it has been validated. To validate a phone number, a token is sent via SMS after requesting it in the SMS management page. This token is then typed-in by the user.
Here is the candidate SMS validation template :
Code is 54321. To validate your phone number and receive Piwik SMS reports please copy this code in the form accessible via Piwik > Settings > SMS.
The validation token does not expire.
Phone numbers can not be modified. To change an already validated number the user will have to remove it and add a new one.
The UI will provide a list of countries to automatically assign the international extension number. The country corresponding to the current language will be selected as the default value.
The phone number input field accepts only numbers.
A report can be created and edited without assigning phone numbers. The report list will display a warning message and the user won’t be able to send the report.
In the report page, when the user has not validated at least one number :
SMS reports are still editable, the form can be saved without a selected phone number but the following message will be displayed in the edit form: “The list of phone numbers is empty because you did not activate a phone number”. A link will be provided for quick access.
SMS Management Page
The SMS management page will be added in “Settings”.
Technical aspects
- This SMS report feature will be developed as a new plugin called MobileMessaging. It will be included in core but disabled by default.
- The code managing the SMS authorization token and phone numbers should be reusable by other features such as SMS alerts. Therefore, the MobileMessaging plugin should work without the PDFReports plugin.
- PDFReports plugin templates will have to implement a hook mechanism.
- Phone numbers and auth tokens will be stored in the option table one line per user with the following structure :
USERNAME__MobileMessagingSettings =
array(
'PhoneNumbers' => array(
'003354827548' => NULL, // NULL : phone number is activated
'00542857842754' => 52123, // !NULL : validation token value
),
'ProviderAuthToken' => 'f4e8za4al', // Only if Super User or if MobileMessagingSettings.DelegatedManagement is set to TRUE
)
- Whether the auth token is managed by the super admin or not will be defined in the option table with the following structure :
MobileMessagingSettings.DelegatedManagement = TRUE // True if users can manage their own SMS account
- The code managing the SMS provider will follow the Service Gateway design pattern to keep an open door for multiple SMS providers.
English
