Welcome to CM Mobile’s documentation!¶

CM Mobile is a Joomla! component for helping Joomla! and mobile applications communicate with together. CM Mobile supports Joomla!’s Users component by default, this provides ability to register a Joomla! user account via mobile applications, with CM Mobile’s session manager user can login and perform actions in the supported components.

Overview¶

CM Mobile is developed by CMExtension. We needed to give our Joomla! extensions ability to connect with our mobile applications, instead of adding this ability to every extension and have duplicated code in them, we built CM Mobile. With CM Mobile, we will not only integrate it with our current and future extensions, but we will also try to integrate with other third-party Joomla! extensions, we hope this will help end users have more choices in finding a solution to build their mobile applications for their Joomla! website.

CM Mobile is not a component which can help you do everything with some mouse clicks, CM Mobile requires coding to add more features and support more components. If you are not a technical user who knows web programming, then you may need to find a developer to help you add your own ideas to CM Mobile, you can also contact us for support.

Technical Requirements¶

CM Mobile is only compatible with Joomla! 3.x.x, we recommend the latest release of Joomla! 3 series. CM Mobile is NOT compatible with Joomla! 1.x.x and 2.5.x.

Please check Joomla!’s Technical Requirements for more information of Joomla!’s requirements.

Support Components¶

Users (included by default in Joomla!)
CM Live Deal (by CMExtension)

Installation¶

Download¶

The installation packages of CM Mobile can be downloaded from our Github repository.

Installation¶

In your Joomla! back-end, you navigate to Extensions -> Extension Manager

Click “Browse” button and select the installation package of CM Mobile on your computer, click “Upload & Install” button to upload the package to your server and install it.

If the package is installed successfully, you receive the message “Installing package was successful.”

_images/installation_install_success.jpg

You can see CM Mobile in Components menu item.

Configuration¶

In your Joomla!’s back-end, you go to Components -> CM Mobile to access CM Mobile component.

The default page of CM Mobile is the dashboard. On the toolbar there is an “Options” button, you click this button to configure the component.

There are the 4 tabs in the configuration page: General, Connection, Session, Permissions.

General¶

Testing (for developer): If testing is enabled, HTTP user agent and session’s checksum are not checked. Developer can request JSON response right from web browser. Session’s token is still required. You should disable testing if your application and website are in production.

Connection¶

“Connection” tab includes the setting options for the connection between CM Mobile and your mobile application. The settings you apply here need to be applied the same in your mobile applicaton, otherwise CM Mobile will not respond to the requests of your mobile application.

HTTP request method: The HTTP request method which is used in connection.
Allowed user agent: Enter the string of your custom user agent. Only the requests which comes with this user agent are handled, the requests come with any other user agents will be ignored. This option gives another filter layer to make sure only your mobile application can connect to the component. You can find ideas for your custom user again at many websites, for example http://www.user-agents.org/.

Session¶

Session lifetime: Session lifetime in hour. Default is 24 hours. If session’s token is older than session’s lifetime, session must be cleared and user must login to create a new session.
Token length: The length of token, default is 32 characters, 200 characters maximum. Token is a string which contains alphabetic and numeric characters characters, it is used to identity user’s session.
Secret key: The string which is used in create and validate checksum. Checksum is sent in every request from mobile application to Joomla! to make sure that the request is come from your mobile application.

Permissions¶

“Permissions” tab contains the permission settings for user groups on your site, you can see this in all Joomla!’s default components, as well as other third-party components.

Because CM Mobile only has user interface in back-end so you may only need to adjust these settings if you allow other users to access your site’s back-end and you want to limit what they can do.

Sessions¶

In CM Mobile’s dashboard, you click “Sessions” item in the component’s toolbar to access the list of sessions.

In this page you can see the list of created sessions, session is created when your user logs into from the mobile application.

Expired sessions have expired date in red color.

You can select sessions and click “Detele” button to delete them. You can also click “Delete expired sessions” to delete only expired sessions without manually selecting them.

You often don’t need to check and delete expired sessions when your site and your application are in production, however when they are in development you may need to delete sessions for testing purposes.

Checksum¶

Checksum is one of many methods in CM Mobile to ensure that request comes from your mobile application and comes from your users.

Checksum is a MD5 string of: token, Joomla! username and secret key. You can set your secret key in CM Mobile’s configuration.

Sample PHP code for generating checksum:

$string = $token . $username . $secretKey;
$checksum = md5($string);

When you send your requests which require authentication, you need to include your token and your checksum in your request. If testing mode is enabled in CM Mobile’s configuration, you only need to include token.

Users component¶

CM Mobile supports the following actions for Users component:

Register for a new account
Login
Logout

Register¶

GET request:

http://yoursite.com/index.php?option=com_cmmobile&task=users.register&format=json&username=YOUR_USERNAME&password=YOUR_PASSWORD&name=YOUR_NAME&email=YOUR_EMAIL

Sample successful response:

{
        "success":true,
        "message":"Your account was created. Successfully logged in.",
        "messages":null,
        "data":{
                "token":"YOUR_TOKEN"
        }
}

Login¶

GET request:

http://yoursite.com/index.php?option=com_cmmobile&task=users.login&format=json&username=YOUR_USERNAME&password=YOUR_PASSWORD

Sample successful response:

{
        "success":true,
        "message":"Login succeeded.",
        "messages":null,
        "data":{
                "token":"YOUR_TOKEN"
        }
}

Logout¶

GET request:

http://yoursite.com/index.php?option=com_cmmobile&task=users.logout&format=json&token=YOUR_TOKEN&checksum=YOUR_CHECKSUM

Sample successful response:

{
        "success":true,
        "message":"Logout succeeded.",
        "messages":null,
        "data":null
}

CM Live Deal component¶

Get deals¶

GET request:

http://yoursite.com/index.php?option=com_cmmobile&task=cmlivedeal.getDeals&format=json&start=PAGINATION_START&limit=PAGINATION_LIMIT

“start” and “limit” are the same to “limitstart” (or “start”) and “limit” in Joomla!’s pagination.

Sample successful response:

{
        "success":true,
        "message":null,
        "messages":null,
        "data":{
                "total":"TOTAL_DEALS",
                "deals":[{
                        "id":"DEAL_ID",
                        "title":"DEAL_TITLE",
                        "description":"DEAL_DESCRIPTION",
                        "fine_print":"DEAL_FINE_PRINT",
                        "starting_time":"DEAL_STARTING_TIME",
                        "merchant_name":"MERCHANT_NAME",
                        "merchant_about":"MERCHANT_ABOUT",
                        "merchant_address":"MERCHANT_ADDRESS",
                        "merchant_latitude":"MERCHANT_LATITUDE",
                        "merchant_longitude":"MERCHANT_LONGITUDE",
                        "merchant_phone":"MERCHANT_PHONE",
                        "merchant_website":"MERCHANT_WEBSITE",
                        "merchant_merchant_facebook":"MERCHANT_FACEBOOK",
                        "merchant_twitter":"MERCHANT_TWITTER",
                        "merchant_pinterest":"MERCHANT_PINTEREST",
                        "merchant_google_plus":"MERCHANT_GOOGLE_PLUS",
                        "ending_time":"DEAL_ENDING_TIME",
                        "thumbnail":"DEAL_THUMBNAIL"
                }, {
                ...
                }]
        }
}

Get deals with filters¶

GET request:

http://yoursite.com/index.php?option=com_cmmobile&task=cmlivedeal.getDeals&format=json&start=PAGINATION_START&limit=PAGINATION_LIMIT&keyword=KEYWORD&category=CATEGORY_ID&city=CITY_ID&latitude=YOUR_LATITUDE&longitude=YOUR_LONGITUDE

CATEGORY_ID is

the ID of an existing category in CM Live Deal if only get the deals in that category.
0 for getting the deals in all categories.

CITY_ID is

the ID of an existing city in CM Live Deal if only get the deals in that city.
0 for getting the deals in all cities.
-1 for getting the deals near your location, you need to provide your latidue and longitude.

Get coupons¶

GET request:

http://yoursite.com/index.php?option=com_cmmobile&task=cmlivedeal.getCoupons&format=json&token=YOUR_TOKEN&checksum=YOUR_CHECKSUM&start=PAGINATION_START&limit=PAGINATION_LIMIT

Sample successful response:

{
        "success":true,
        "message":null,
        "messages":null,
        "data":{
                "total":"TOTAL_COUPONS",
                "coupons":[{
                        "id":"COUPON_ID",
                        "code":"COUPON_CODE",
                        "created":"DATE_TIME_WHEN_COUPON_CREATED",
                        "deal_name":"DEAL_NAME",
                        "deal_ending_time":"DEAL_ENDING_TIME",
                        "deal_fine_print":"DEAL_FINE_PRINT",
                        "deal_expired":"TRUE_IF_DEAL_IS_EXPIRED",
                        "merchant_name":"MERCHANT_NAME",
                        "merchant_about":"MERCHANT_ABOUT",
                        "merchant_address":"MERCHANT_ADDRESS",
                        "merchant_latitude":"MERCHANT_LATITUDE",
                        "merchant_longitude":"MERCHANT_LONGITUDE",
                        "merchant_phone":"MERCHANT_PHONE",
                        "merchant_website":"MERCHANT_WEBSITE",
                        "merchant_merchant_facebook":"MERCHANT_FACEBOOK",
                        "merchant_twitter":"MERCHANT_TWITTER",
                        "merchant_pinterest":"MERCHANT_PINTEREST",
                        "merchant_google_plus":"MERCHANT_GOOGLE_PLUS"
                        }, {
                        ...
                        }]
        }
}

Get coupons with filters¶

GET request:

http://yoursite.com/index.php?option=com_cmmobile&task=cmlivedeal.getCoupons&format=json&token=YOUR_TOKEN&checksum=YOUR_CHECKSUM&start=PAGINATION_START&limit=PAGINATION_LIMIT&keyword=KEYWORD&status=STATUS

STATUS is

-1 for getting all coupons.
1 for only getting active coupons.
0 for only getting expired coupons.