mozilla-b2g/gaia — pull request #3757 by lodr (2012-08-23 18:03:52+00:00)
Title: Feature Cost Control

# Overview

This application intends to cover the requirements for [Gaia/System/ConsumptionControl](https://wiki.mozilla.org/Gaia/System/ConsumptionControl). The [specification document](https://wiki.mozilla.org/images/8/87/Credit_and_Data_Usage_App.pdf) can be found there.

## Note before trying

Unless you have a Vivo SIM card and can test in a real device (not desktop), this application does not work.

Furthermore, remember Vivo is a Brazilian company so if you test out of Brazil then you were in roaming son automatic updates will be disabled.

## How Cost Control application works

Cost Control is very coupled to Vivo cost control service. All is supported by an SMS interface which is very ugly. To update the balance, the user sends a **free** message to a specific number and, in return, he receives another SMS with his credit.

To top up, the user buys a scratch card with a number. Then he types that number in a SMS and send it to another Vivo number. The user receives a confirmation but not a credit update, this should be requested manually.

The Cost Control application tries to automatize these flows.

## Main changes:

Changes introduced by this PR can be categorized in:
* Building Blocks
* Settings
* System
* SMS application
* Cost Control application

## Building blocks

The application seems to introduce a lot of files but many of them are images or part of the [Building Blocks](https://github.com/mozilla-b2g/Gaia-UI-Building-Blocks). They are though to be used as a package so I did not remove any of them except demonstration assets.

## Settings

Settings has been modified trying to simulate the OEM process that Vivo could follow before selling the devices. Settings DB now include keys for destination numbers, valid senders, regular expressions to identify SMS and so on. Furthermore it includes the SMS blacklist, continue reading for more details.

## System

Three modifications has been made in system.

First viewed is now the quick settings are at the bottom of the utility tray and just above, there is the Cost Control widget. Second, window_manager.js has been modified to include Cost Control into the OOP blacklist. And third, a cost_control.js has been added to perform as a bridge between System and Cost Control applications. It is in charge of dispatch some System events to the CostControl application.

## SMS application

The SMS application now includes a blacklist to mute notification and other feedback for some senders. To prevent the user from be warned each time the credit is updated, the Vivo number for this service has been added to it. Some other numbers from Vivo have not added because they normally include some more information rather than only service info as ads or promotions.

## Cost Control application

The Cost Contro application is split into three main modules:

* The service
* The utility try widget
* The application itself

The architecture of the module is client-server in a event-listener flavour. The service is the entry point for the functionalities. Several clients (the application and the widget in this case) register callbacks in the service and listen for events dispatched from it.

Widget is a silly module that shows the current balance. Tapping on it, the user is redirected to the Cost Control Application. This application holds the advanced functionality. It allows the user to update the balance or top up and will include telephony information, data usage and settings in near future.

# Flaws and future work

Functionality is not completely implemented. Here is a brief of what remain:

* Icon for the application
* Icons for notifications
* Several visuals

Furthermore, We should study how to decouple the application from Vivo in a future. Once all functionality was implemented, the coupling effect wont be evident because data usage and telephony (2 out of the 3 application's main features) are company independent.

## Cost Control

* Countdown for top up
* Low credit state and zero credit state
* Notifications for these states
* Automatic balance update when focusing the application

## Telephony

Not implemented at all

## Data usage

Not implemented at all

## Settings

Not implemented at all