Using AEM Mobile specific Cordova-enabled plug-ins

entityName:
String – the name of the entity

entityType:
String – the type of the entity

forceUpdate:
Boolean – if 'true', always query the server for the latest version

success:
Function – the success callback

error:
Function – the error callback

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.

entityOrEntityList:
Entity or EntityList object – The entity or entities for which to retrieve entitlement info

success:
Function – The success callback

error:
Function – the error callback

on success:

[
{
“entityName” : <entityName1>,
“isEntitled” : true or false
},
{
“entityName” : <entityName2>,
“isEntitled” : true or false
},
]

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.

entity: The collection download status.

success: Function - the success callback

error: Function - the error callback

on success:
{ "entityName" : "isSavable" : "progressPercent" :  "downloadState" : }

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.

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.

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.

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.

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.

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.

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.

success:
Function - the success callback

error:
Function - the error callback

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.

success: Function - the success callback

error: Function - the error callback

Supports Article

The ContentLocation object includes pageNumber and totalPageCount.
The pageNumber is zero-based, so 0 is the first page of the article. These values reflect the physical location of the content in the article. For HTML articles, totalPageCount is 1 and pageNumber will be 0.

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.
Any request to this API made while a previous request is in flight will return a network rate limit exceeded error until any previous request returns success or failure.

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.

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.

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.

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.

success: The success callback

error: The error callback

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.

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.

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

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.