Prerequisite knowledge
- Understanding of AEM Mobile
- Knowledge of creating and publishing content through the On-Demand Portal
- Knowledge about JavaScript
Required products
- AEM Mobile
Experience Manager Mobile specific Cordova-enabled plugins are a set of JavaScript APIs that provide access to specific data related to the application and the current article being viewed. To utilize the AEM Mobile Cordova plug-ins, articles must have the "Enable Extensibility Features" option in article properties selected on the On-Demand Services portal or set isTrustedContent parameter in the article entity metadata to true via the On-Demand Services API.
The AEM Mobile specific Cordova-enabled plugins use the namespace cq.mobile to avoid conflicts with other Cordova-powered plugins. The API consists of several modules, with each module being a singleton with some number of methods and properties.
For information about using Core Cordova APIs, see Using Cordova plug-ins in AEM Mobile.
Availability
This plugin defines the global cq.mobile.context object. It is not available until after the deviceready event.
Name | Type | Volatile | Comments |
cq.mobile.context.collection | Entity1 | No | Could be empty (null) if the current context is an orphaned context. |
cq.mobile.context.entity | Entity1 | No | Returns the entity in scope. Scopes:
|
cq.mobile.context.nextEntity | Entity1 | No | Could be empty (null) if this is the last entity. Note: The next entity for a dynamic banner is the entity following the dynamic banner in a browse view, which might be different from the next entity in the elements array for the parent collection. This is different from what will happen when nextEntity is called from an article (which will return the order from the parent collection's child elements array). |
cq.mobile.context.previousEntity | Entity1 | No | Could be empty (null) if this is the first entity. For dynamic banners, see the above note for nextEntity. |
cq.mobile.context.type | String | No | Possible values: "article", "overlay", "dynamicBanner" |
1 Entity contains the following fields as described in the next section: id, metadata, rootPath, and type
Name | Type | Comments |
id | String | |
metadata | Object2 | metadata specific to entity type |
rootPath | String | Applies only to articles and dynamic banners. Represents the root path of the entity running in the current context. Can be used as a reference to other plugins to build a path to a resource contained within the entity. (iOS and Android only). |
type | String | Possible values: "collection", "article", "banner", "dynamicBanner" |
2 Metadata object will contain a different set of fields depending on the Entity type, as described in the next section.
Name | Type | Support for Entity | Comments |
abstract |
String | Article, Collection, Banner, Dynamic Banner | |
accessState | String | Article |
Possible values: "free", "metered", "protected" |
adCategory | String | Article, Dynamic Banner |
|
adType | String | Article, Dynamic Banner |
Possible values: "static", "EFT" |
allowDownload | Boolean | Collection | |
articleText | String | Article |
|
author | String | Article |
|
authorURL | String | Article |
|
availabilityDate | String | Article, Collection, Banner, Dynamic Banner | |
advertiser | String | Article, Dynamic Banner |
|
category | String | Article, Collection, Banner, Dynamic Banner | |
created | String | Article, Collection, Banner, Dynamic Banner | |
department | String | Article, Collection, Banner, Dynamic Banner | |
entityName | String | Article, Collection, Banner, Dynamic Banner | |
hideFromBrowsePage | Boolean | Article |
|
importance | String | Article, Collection, Banner, Dynamic Banner | Possible values: "low", "normal", "high" |
isAd | Boolean | Article, Dynamic Banner |
|
isIssue | Boolean | Article |
|
keywords | String Array | Article, Collection, Banner, Dynamic Banner | |
lateralNavigation | Boolean | Collection | |
modified | String | Article, Collection, Banner, Dynamic Banner | |
openTo | String | Collection | Possible values: "browsePage", "contentView" |
productIds | String Array | Collection | |
published | String | Article, Collection, Banner, Dynamic Banner | |
readingPosition | String | Collection | Possible values: "reset", "retain" |
shortAbstract | String | Article, Collection, Banner, Dynamic Banner | |
shortTitle | String | Article, Collection, Banner, Dynamic Banner | |
socialShareUrl | String | Article, Collection, Banner, Dynamic Banner | |
tapAction | String | Banner | |
title | String | Article, Collection, Banner, Dynamic Banner | |
url | String | Article, Collection, Banner, Dynamic Banner | |
version | String | Article, Collection, Banner, Dynamic Banner |
Name | Arguments | Response | Comments |
getEntity (entityName, entityType, forceUpdate, success, error) |
entityName: entityType: forceUpdate: success: error: |
on success: an Entity object Note: null is an allowed return value for Dynamic Banners (since this is not a required property for this entity type) on failure: cq.mobile.contextError object with populated code property |
Supports Article, Banner, Collection, Dynamic Banner entityName must match the name (not title) found in the On-Demand Services. entityType must match values found in Entity.type If forceUpdate is false and the entity is cached, that entity is returned. It may not be the latest version of that entity. If forceUpdate is true but cannot connect to the server, the existing entity is returned if available in the cache. If nothing exists in the cache, a network error is returned. If unable to connect to the server but cannot find the requested entity (or it is restricted and the user is not entitled), an Entity Not Found error is returned. |
getEntitlementInfo (entityOrEntityList, success, error) |
entityOrEntityList: success: error: |
on success: [ on failure: cq.mobile.contextError object with populated code property |
Supports Collection getEntitlementInfo() will only return entitlement information for collections. If a non collection Entity object is passed, a Wrong Entity Type error is returned. If an EntityList object is passed, only entitlementInfo for collection objects will be returned. If there are no collections, the returning array will be empty. The 26th request (and any subsequent request) to this API within a one minute period will return a Network Rate Limit Exceeded error. If the device is offline, whatever cached entitlement information is returned. If the device is online and the entitlement service cannot be contacted, a Network error is returned. |
getEntityStatus (entity, success, error) |
entity: The collection download status. success: Function - the success callback error: Function - the error callback |
on success: on failure: cq.mobile.contextError object with populated code property |
Supports Collection getEntityStatus() will retrieve download status information for the collection Entity. Status Information: "entityName": the name of the collection Entity. "isSavable": the collection must be marked as download (save) allowed in collection properties, and have sufficient entitlement to return true. "progressPercent" : amount of the collection currently downloaded from 0 to 100 percent. Note: this value may not always be accurate if the information has been flushed from memory. See the download states later in this document. Errors: getEntityStatus() will only return entitlement status information for collections. If a non-collection Entity object is passed, not found, or has not been initialized, an error is returned. See the list of errors later in this document. |
saveEntity(entity, isSilent, success, error) | entity: The collection to download and save. isSilent: BOOL - (Android only) If true, the entity is saved in the background with no notification. success: Function - the success callback. error: Function - the error callback. |
on success: { "rawEntity" : "downloadPercent" : "downloadState" } on failure: Error with populated code property |
Supports Collection saveEntity() will download and save the given collection Entity. It is the equivalent of hitting the download button in the UI. Success callback: The success callback returns the entity object being saved. Additionally, the success callback will be called every time there is a progress update of the download. The progress can be tracked through the "downloadPercent" and "downloadState" return values. When the save/download is initiated, the collection download should become the current active download. If another collection download is started, that collection will become the active download, and the first collection will become paused. The first collection should resume downloading and the state become active when the second collection finishes downloading. Errors: saveEntity() will download only collections. If a non-collection Entity object is passed, if the collection is not found, or if the download is cancelled, an error is returned. See the list of errors later in this document. |
archiveEntity(entity, success, error) | entity: Entity object - the entity to archive (un-save) success: Function - the success callback error: Function - the error callback |
on success: an Entity object on failure: an error with populated code property |
Supports Collection archiveEntity() will archive (opposite of saveEntity()) the given collection Entity. It is the equivalent of tapping the check mark button in the UI. If the collection has completely downloaded and saved, archiveEntity will mark the collection as non-persistent, and subject to purge. If the collection is actively downloading, or is queued to download, the download will be cancelled, and the content that had been downloaded will be marked as purgeable. Success: the archived Entity object is returned. Errors: archiveEntity() will archive only collections. If a non-collection Entity object is passed or if the collection is not found, an error is returned. |
getSavedEntities(success, error) | success: Function - the success callback error: Function - the error callback |
on success: array of Entity objects on failure: error with populated code property |
Supports Collection getSavedEntities() will return an array of Entity objects that are either completely downloaded or queued to be downloaded, and will be saved. |
getBackgroundImage (width, height, success, error) |
width: Number - the requested width height: Number - the requested height success: Function - the success callback error: Function - the error callback |
on success: a file URL to the background image as argument of the success callback on failure: cq.mobile.contextError object with populated code property |
Supports Collection The Runtime viewer does not scale the image, instead it will return the image size that is closest to the size specified. Will request for the background image from the On-Demand Services if the image is not cached on the device. In most cases, the image will remain in the cache for the immediate future. If the call is attempted on entities of type other than Collection, the error callback will be called. |
getThumbnailImage (width, height, success, error) |
width: Number - the requested width height: Number - the requested height success: Function - the success callback error: Function - the error callback |
on success: a file URL to the thumbnail image as argument of the success callback on failure: cq.mobile.contextError object with populated code property |
Supports Article, Banner, Collection, Dynamic Banner The Runtime viewer does not scale the image, instead it will return the image size that is closest to the size specified. Will request for the thumbnail image from the On-Demand Services if the image is not cached on the device. In most cases, the image will remain in the cache for the immediate future.
|
getSocialSharingImage (width, height, success, error) |
width: Number - the requested width height: Number - the requested height success: Function - the success callback error: Function - the error callback |
on success: a file URL to the social sharing image as argument of the success callback on failure: cq.mobile.contextError object with populated code property |
Supports Article The Runtime viewer does not scale the image, instead it will return the image size that is closest to the size specified. Will request for the social sharing image from the On-Demand Services if the image is not cached on the device. In most cases, the image will remain in the cache for the immediate future. If the call is attempted on entities of type other than Collection, the error callback will be called. |
getChildren(success, error) | success: error: |
on success: an EntityList object on failure: cq.mobile.contextError object with populated code property |
Supports Collection The EntityList will contain all the non-restricted child entities for this collection that are in the cache. If none exist, there is an attempt to download the first server page of children. |
getContentLocation(success, error) | success: Function - the success callback error: Function - the error callback |
on success: returns ContentLocation object | Supports Article The ContentLocation object includes pageNumber and totalPageCount. |
For additional details about these metadata properties, see Integrating third-party systems with AEM Mobile.
Name | Type | Comments |
entities | Array | List of entities. Possible entities: 'article', 'collection', ‘banner'. |
hasNextPage | Boolean | If 'true', there are more entities in the list. Use the method getNextPage() to retrieve the next page of entities from the list. |
Name | Arguments | Response | Support for Entity | Comments |
getNextPage (success, error) |
success: error: |
on success: the entities property will contain additional Entity items, and the hasNextPage property will be updated on failure: cq.mobile.contextError object with populated code property |
Collection | If getNextPage() is called when hasNextPage is false, the No More Entity Pages error will be returned. The entities returned will not be restricted. Restricted information may have changed since the last time getNextPage() was called. If so, the Entity Page Out of Date error will be returned. You will have to call getEntity() on the collection to pull the updated collection and call getChildren() with this updated collection. |
The cq.mobile.contextError is an enumeration object, defining all the supported error codes for context methods.
Name | Value |
cq.mobile.contextError.UNKNOWN_ERROR |
0 |
cq.mobile.contextError.INVALID_ARGUMENT_ERROR |
10 |
cq.mobile.contextError.ENTITY_IMAGE_TYPE_NOT_SUPPORTED_FOR_ENTITY_ERROR |
11 |
cq.mobile.contextError.NETWORK_ERROR |
20 |
cq.mobile.contextError.NETWORK_RATE_LIMIT_EXCEEDED_ERROR |
21 |
cq.mobile.contextError.ENTITY_IMAGE_ENTITY_NOT_FOUND_ERROR |
40 |
cq.mobile.contextError.ENTITY_IMAGE_NETWORK_ERROR |
41 |
cq.mobile.contextError.ENTITY_IMAGE_NOT_FOUND_ERROR |
50 |
cq.mobile.contextError.ENTITY_NOT_FOUND_ERROR |
61 |
cq.mobile.contextError.WRONG_ENTITY_TYPE_ERROR |
71 |
cq.mobile.contextError.NO_MORE_ENTITY_PAGES_ERROR |
72 |
cq.mobile.contextError.ENTITY_PAGE_OUT_OF_DATE_ERROR |
73 |
cq.mobile.contextError.ENTITY_OUT_OF_DATE_ERROR | 74 |
cq.mobile.contextError.ENTITY_SAVE_FAILURE | 80 |
cq.mobile.contextError.ENTITY_SAVE_CANCELLED | 80 |
The cq.mobile.downloadState is an enumeration object, defining all the supported error codes for collection download methods.
Name | Value |
cq.mobile.downloadState.NONE |
0 |
cq.mobile.downloadState.DOWNLOAD_PAUSED |
1 |
cq.mobile.downloadState.DOWNLOAD_ACTIVE |
2 |
cq.mobile.downloadState.DOWNLOAD_COMPLETE |
3 |
The device module provides the value from the native code. Please note that these properties reside in a different name space from the Cordova device plugin (window.cq.mobile.device vs window.device).
Name | Type | Volatile |
Comments |
cq.mobile.device.class | String | No | Possible values: Phone, Tablet (Windows returns only Tablet since phones are not supported) |
cq.mobile.device.vendorId | String | No | iOS only (see IdentifierForVendor in iOS developer guide) |
Availability
This plugin defines the global cq.mobile.application object. It is not available until after the deviceready event.
Name | Type | Volatile | Comments |
cq.mobile.application.id | String | No | example: com.adobe.create |
cq.mobile.application.pushNotificationToken | String | No | Push notification token for the device (device token on iOS, Registration ID on Android, Windows viewer hasn’t implemented push notification so the value will be “undefined” until then) |
cq.mobile.application.runtimeVersion | String | No | example: 2015.5.1 |
cq.mobile.application.version | String | No | How the app is versioned, such as 1.0.4 |
cq.mobile.application.isAppSearchEnabled | Boolean | Yes |
Check whether Search is enabled |
cq.mobile.application.isSocialSharingEnabled | Boolean | Yes | Check whether Social Sharing is enabled |
Availability
This plugin defines the global cq.mobile.user object. It is not available until after the deviceready event.
Name | Comments |
isauthenticatedchanged | Event is triggered when the user changes the authentication state. Clients should query the user object for the latest state. |
authtokenchanged | Event is triggered when the user authentication tokens changes. Clients should query the user object for the latest state. |
Name | Type | Volatile | Comments |
cq.mobile.user.authToken | String | Yes | |
cq.mobile.user.isAuthenticated | Boolean | Yes |
Name | Arguments | Response | Comments |
setAuthToken(authToken, success, error) | authToken: string- the requested value for authToken success: Function - the success callback error: Function - the error callback |
on success: Calls success callback with no parameters on failure: Calls error callback with cq.mobile.userError code set |
This call will successfully execute only on projects that have a generic identity provider setup or have only a direct entitlement provider (no identity provider). Otherwise, an authentication support error is returned when this API is called. If the setAuthToken call fails for some reason (a 502, 503, or 504 is returned), ideally the viewer will retry once. If the retry fails or no retry is executed, a network error is returned. The 11th request to this API in a one minute period will return a network rate limited exceeded error, as will every subsequent request after the 11th until a minute has elapsed since the 1st request. |
launchSignInUX(error) | error: Function - the error callback | on failure: Calls error callback with cq.mobile.userError code set | If authentication occurs through an entitlement server, the native sign-in dialog box is displayed. If authentication occurs through an identity provider, the authentication URL is displayed in a web view on device viewers, or it redirects to the authentication URL on Desktop Web Viewer. If no authentication is specified in the project, calling this API will return an Authentication Support error. If the user is already authenticated, an Invalid Authentication State error is returned. If the web viewer is unable to retrieve authentication settings, a Network error is returned. Users can still sign out of device viewers while offline. |
signOut(error) | error: Function - the error callback | on failure: Calls error callback with cq.mobile.userError code set | Signs out the user, and refreshes signed out state to be reflected in the UI. If no authentication is specified in the project, calling this API will return an Authentication Support error. If the user is already authenticated, an Invalid Authentication State error is returned. If the web viewer is unable to sign out, a Network error is returned. Device viewers will used cached authentication settings if authentication settings cannot be retrieved. |
refreshSignIn(success, error) | success: Function - the success callback error: Function - the error callback |
on success: Calls success callback with no parameters on failure: Calls error callback with cq.mobile.userError code set |
Use this API to attempt to refresh the user's sign in only when you determine that the current session is no longer valid. This API will refresh the sign in only in two scenarios: 1) The project is set up with an entitlement service but no custom authentication. Calling this API will result in a renewAuthToken call on the entitlement service. 2) The project is set up with an OAuth identity provider that provides a refresh token. Calling this API will attempt to use that refresh token to refresh the sign in session. In both scenarios, the refresh may not be successful. If this occurs, the user will be signed out. In all other scenarios—including if this API is called on a project set up with a SAML or an OAuth identity provider that doesn’t support refresh—this refresh will fail and sign the user out and return the user home. If no authentication is specified in the project, calling this API will return an Authentication Support error. If the user is not authenticated, an Invalid Authentication State error is returned. If the viewers are offline and sign in cannot be refreshed, a Network error is returned. Device viewers will used cached authentication settings if authentication settings cannot be retrieved. |
Бележка:
An "UNKNOWN_ERROR" code is returned in the error callback when an unexpected error occurs with any of these API calls.
The cq.mobile.userError is an enumeration object, defining all the supported error codes for user methods.
Name | Value |
cq.mobile.userError.UNKNOWN_ERROR |
0 |
cq.mobile.userError.INVALID_ARGUMENT_ERROR |
10 |
cq.mobile.userError.AUTHENTICATION_SUPPORT_ERROR |
11 |
cq.mobile.userError.INVALID_AUTHENTICATION_STATE |
12 |
cq.mobile.userError.NETWORK_ERROR |
41 |
cq.mobile.userError.NETWORK_RATE_LIMIT_EXCEEDED_ERROR |
42 |
cq.mobile.userError.UNAUTHORIZED |
43 |
Availability
This plugin defines global entitlement object, which provides methods related to entitlement and purchase. It is not available until after the deviceready event.
Name | Type | Comments |
productId | String | The product/subscription id that appears in the Products & Subscription section of the Portal. |
label | String | The product/subscription name that appears in the Products & Subscription section of the Portal. It will be null if not set by the user. |
description | String | The product/subscription description that appears in the Products & Subscription section of the Portal. It will be null if not set by the user. |
price | String | The price returned from the corresponding store. Null if product is free. |
offerType | String | Could be "subscription" or "product." |
Name | Type | Comments |
subscriptionOffers | Array | An array of Offer objects. Is empty if user has an active subscription. |
subscriptionState | Object | A subscriptionState object. |
Name | Type | Comments |
isSubscriber |
Boolean | True if the user has been a subscriber at any point in time. Note that subscriptionState.isSubscriber is identical to subscriptionState.store.isSubscriber and subscriptionState.integrator.isSubscriber. |
isActiveSubscriber |
Boolean | True if the user has an active subscription. |
store | Object | Store object which contains subscription state to product store. |
integrator | Object | Integrator object which contains subsciption state to the entitlement integrator. |
Name | Type | Comments |
isSubscriber |
Boolean | True if the user has been a subscriber at any point in time. |
isActiveSubscriber |
Boolean | True if the user has an active subscription. |
expirationDate | Number | The timestamp in milliseconds since the expiration date. This value could be null if the subscription (either from the store or entitlement integrator) has no expiration date. |
subscriptionType | String | Could be "allAccess" or "standard." Valid only if isSubscriber is true. |
id | String | Product id of the subscription product in the store. |
Name | Type | Comments |
isSubscriber |
Boolean | True if the user has been a subscriber at any point in time. |
isActiveSubscriber |
Boolean | True if the user has an active subscription. |
expirationDate | Number | The timestamp in milliseconds since the expiration date. This value could be null if the subscription (either from the store or entitlement integrator) has no expiration date. |
customData | String | customData will not be set if the sibling isSubscriber is false. If isSubscriber is true, it may or may not be set. customData can be returned by the integrator. It is intended to contain data that is transparent to Adobe and meaningful only to the customer. |
Name | Arguments | Response | Comments |
getSubscriptionInfo(success, error) |
success: The success callback error: The error callback |
On success: A SubscriptionInfo object. |
This method returns the subscription info for the current publication and device. After 60 API requests made in a one minute period, any subsequent request to this API will return an error until a minute has elapsed since the first request. Desktop Web Viewer does not support this API and always returns an error. |
getOffers(collectionName, success, error) |
collectionName: String - the name of the collection success: Function - the success callback error: Function - the error callback |
on success: an array of Offer objects on failure: an error with populated code property |
collectionName must match name found in the Portal. If the requested entity cannot be found or if it is restricted and not visible, an error is returned. Cached offers for the requested entity are returned if available. Otherwise, a network request to Entitlement Service will occur to fetch the offers. After 60 network requests to Entitlement Service in a one minute period is made, any subsequent request to this API results in an error until a minute has elapsed since the first request. Desktop Web Viewer does not support this API and always returns an error. |
purchaseOffer(productId, success, error) |
productId: String - The productId of the offer to purchase success: Function - the success callback error: Function - the error callback |
on success: a purchase request is initiated on failure: Calls error code |
This method initiates a purchase request. |
restorePurchases(successCallback, errorCallback) | success: Function - the success callback error: Function - the error callback |
on success: a restore purchase request is initiated on failure: Calls error code |
This method will initiate restore previous purchases for the user. After 5 API requests are made in a one minute period, any subsequent request to this API will return an error until a minute has elapsed since the first request. |
The cq.mobile.entitlementError is an enumeration object, defining all the supported error codes for entitlement methods.
Name | Value |
cq.mobile.entitlementError.UNKNOWN_ERROR | 0 |
cq.mobile.entitlementError.INVALID_ARGUMENT_ERROR |
10 |
cq.mobile.entitlementError.ENTITY_IMAGE_TYPE_NOT_SUPPORTED_FOR_ENTITY_ERROR | 11 |
cq.mobile.entitlementError.INVALID_AUTHENTICATION_STATE | 12 |
cq.mobile.entitlementError.NETWORK_ERROR | 20 |
cq.mobile.entitlementError.NETWORK_RATE_LIMIT_EXCEEDED_ERROR | 21 |
cq.mobile.entitlementError.ENTITY_IMAGE_ENTITY_NOT_FOUND_ERROR |
40 |
cq.mobile.entitlementError.ENTITY_IMAGE_NETWORK_ERROR | 41 |
cq.mobile.entitlementError.ENTITY_IMAGE_NOT_FOUND_ERROR | 50 |
cq.mobile.entitlementError.ENTITY_NOT_FOUND_ERROR | 61 |
cq.mobile.entitlementError.WRONG_ENTITY_TYPE_ERROR | 71 |
cq.mobile.entitlementError.NO_MORE_ENTITY_PAGES_ERROR | 72 |
cq.mobile.entitlementError.ENTITY_PAGE_OUT_OF_DATE_ERROR | 73 |
cq.mobile.entitlementError.ENTITY_OUT_OF_DATE_ERROR | 74 |
cq.mobile.entitlementError.ENTITY_SAVE_FAILURE | 80 |
cq.mobile.entitlementError.ENTITY_SAVE_CANCELLED | 81 |
2017 March 16
Added API information for downloading collection entities.
Added API information for purchasing and entitlement.
2017 January 10
Added cq.mobile.application.isAppSearchEnabled and cq.mobile.application.isSocialSharingEnabled (see Application section)
2016 August 9
Added getLocationContent (see Context section)
2016 June 30
Added setAuthToken (see User section)
2016 June 23
Added the ability to traverse the On-Demand Services collection structure:
- Updating the entity metadata with support for banners (see Context tab).
- Added getEntity() to request for the article/banner/collection entity (see Context tab).
- Added getEntitlementInfo() to request for the entitlement information for the collection (see Context tab).
- Added getChildren() to request for the list of immediate child entities for the collection (see Context tab).
- Added getNextPage() to request for the next page of entities from the list returned from getChildren() (see Context tab).
- Added enumeration objects to define error codes for methods used in cq.mobile.context and cq.mobile.user (see Context and User tab).