AEM Mobile content personalization aem-mobile-content-personalization
The AEM Mobile content personalization feature allows AEM Authors to personalize mobile app content by leveraging Adobe Target. This allows the delivery of targeted offers to mobile application users. Adobe Experience Manager Mobile provides the ability to create, target, and deliver content that will provide the user with content that is specific for their own individual tastes.
As is often the case in AEM, in order for authors to begin creating this content, administrators and developers need to first prepare the environment.
AEM dministrators are required to establish a connection between AEM Mobile and the Adobe Target Cloud Service.
Meanwhile, AEM Mobile developers need to modify their existing scripts to facilitate targeted content authoring.
For Administrators for-administrators
There’s a number of steps that need to come together before content authors can start to generate targeted content for mobile apps: There’s getting the right set of permissions for users and groups, creating cloud services, configuring the application for the activity, and finally generating the content.
This article will guide you through the process used to configure the AEM Mobile Hybrid Reference Application for targeting.
The assumption going forward is that the AEM Mobile Hybrid Reference Application has been successfully deployed and accessible via the AEM Mobile Dashboard.
Before authors can generate targeted content within an applications, your AEM instance needs to be configured with the Adobe Target Cloud Service.
Permissions permissions
Users that need access to the personalization console need to be part of the target-activity-authors group.
It is suggested that as part of the users and group setup that the target-activity-group should be added to the apps-admins group. By adding the target-activity-authors group this will allow users ability to see the Personalization navigation menu entry.
Cloud Services cloud-services
To get targeted content working for mobile applications there are two services that need to be configured: The Adobe Target Service and the Adobe Mobile Services service. The Adobe Target Service provides the engine for processing client requests and returning the personalized content. The Adobe Mobile Services service provides the connection between the Adobe services and the mobile application via the ADBMobileConfig.json file which is consumed by the AMS Cordova plugin. From the AEM Mobile Dashboard you can configure your application by adding the two services.
From the AEM Mobile Dashboard locate the Manage Cloud Services and click the + button.
From the Add Cloud Service wizard select the “Adobe Target” cloud service card and click Next.
From the Select a Configuration dropdown you can either create a new configuration or select from an existing one. To create a new configuration select “Create Configuration” from the dropdown. Enter a title for the Target configuration. Enter your client code, email, and password that are associated with your Target account. If you do not know the values for these fields contact the Adobe Target support. Click the “Verify” button to validate the credentials. Once verified, click the Submit button to create the cloud service.
After completion of the wizard the Manage Cloud Service tile will contain the Target cloud service, however it contains a warning about a missing Adobe Mobile Service account.
Adobe Mobile Services adobe-mobile-services
It is necessary to link a Adobe Mobile Services (AMS) account to the application as well, the AMS service provides the required ADBMobileConfig.json file which contains the Target client code information. Before creating an association with the AMS account, the AMS account needs to be modified by a user that has permissions to AMS.
Client Code client-code
To login to the AMS services visit https://mobilemarketing.adobe.com, select the mobile application and click the settings. Locate the SDK Target Options field and place the client code into the field and click Save.
Now that the client code has been associated with the mobile application, when the AMS cloud service is configured via the Adobe Mobile Dashboard the settings for the service settings will be delivered via the ADBMobileConfig.json file.
Adobe Mobile Service Cloud Service adobe-mobile-service-cloud-service
Now that AMS has been configured, it’s time to associate the mobile application in the Adobe Mobile Dashboard. From the AEM Mobile Dashboard locate the Manage Cloud Services and click the + button.
Select the Adobe Mobile Services card and click Next.
From the Create or Select wizard step select the Mobile Service dropdown and select the Create Configuration entry. Provide a title, company, username, password and select the appropriate data center. If you do not know these values contact your Adobe Mobile Service administrator to obtain them. Once all fields have been filled out click the Verify button. The verification process goes to AMS and verifies the credentials for the account, and upon successful validation, a list of Mobile Applications will be populated where you select the associated mobile application from the dropdown. Click the Submit button to complete the wizard. The process may take a bit of time to obtain the configuration data and any associated analytics with the application. Once the process is complete click the Done button from the modal to return back to the Adobe Mobile Dashboard.
Returning back to the Mobile Dashboard the Manage Cloud Services tile will contain the AMS cloud service. You will also note that the Analyze Metrics tile will be populated with lifecycle reports.
For Authors for-authors
Prerequisite: As mentioned above, administrators need to configure the connection to the Adobe Target Service before authors can generate new targeted content.
Once the Administrator has configured the two cloud services and the developer has configured the mobileappoffers handler, content authors can now start generating targeted experiences.
Authoring targeted content within an AEM Mobile app follows a similar procedure to authoring AEM Sites:
See here for a complete overview on Authoring targeted content in AEM
For Developers for-developers
AEM developers building mobile applications should continue to follow the patterns commonly used throughout AEM when developing components. Here, we will walk you through the necessary steps to enable content authors to create targeted content:
Adobe Target ContentSync Handlers adobe-target-contentsync-handlers
To deliver content to the user’s device content is generated by rendering the offers which are created by AEM content authors. To handle the rendering of target offers there is a new content sync handler that will process the offers. Using the Hybrid Reference Application as our sample, the en (english) content package contains the ContentSyncConfig with a mobileappoffers handler. The next step is crucial for rendering offers to the device. The mobileappoffers handler has a path property that identifies the path to the personalization activity that are to be used for the application.
For example if there is an activity that is located at /content/campaigns/hybridref copy this path and paste it as the value to the path property of the mobileappoffers handler.
Once the activities path has been set in the mobileappoffers handler’s path property save the handler. The handler will now be ready to start rendering offers for our mobile devices.
Render Mode render-mode
The mobileappoffers handler is configured differently for publish and dev setups. For publish setups there is a property called renderMode with a value of publish set on the cq:ContentSyncConfig node. The mobileappoffers handler references the renderMode and, if set to publish, will modify the mbox id that gets created. By default, mboxes that are created by AEM have an --author value appended to the mbox id. This identifies that the activity has not been published and should use the unpublished campaign for offer resolutions.
When content is staged via the Adobe Mobile Dashboard, staged content is considered production ready content and is rendered via the non-dev Content Sync Config. Rendering this way will cause the --author to be removed from all mbox ids and expect a published activity to be available on the Target server. Before testing staged content make sure the activity has been published.
Personalization App Development personalization-app-development
Components components
The foundation for any content is typically a page component that extends either one of the base AEM page components wcm/foundation/components/page or foundation/components/page depending if you’re using HTL or JSPs. The duration of these steps will focus on using the wcm/foundation/components/page component. The basic structure of the page component is broken down into multiple scripts, with each script providing the specific purpose of allowing the developer to organize and override their code if needed. The two scripts that are of interest for Personalization is the head.html and body.html. These two scripts provide an area where code can be injected to support the Context Hub, Cloud Services, and Mobile authoring.
Here is an overview of the two primary scripts used to enable content targeting.
head.html head-html
To provide the author the ability to target their content the target menu needs to be added to the page so that the author can change context from edit mode to targeting mode. To enable this feature, the developer should modify the head.html script to include the following snippet of code near the top of the head.html or as close to the <title></title> element as possible.
<meta data-sly-test="${!wcmmode.disabled}">
<div data-sly-call="${clientLib.all @ categories='personalization.kernel'}" data-sly-unwrap></div>
<div data-sly-resource="${'config' @ resourceType='cq/personalization/components/clientcontext_optimized/config'}" data-sly-unwrap></div>
<div data-sly-resource="${'contexthub' @ resourceType='granite/contexthub/components/contexthub'}" data-sly-unwrap></div>
</meta>
To provide authors the ability to preview the targeted content, the editor needs to be able to locate the configuration of the Adobe Target cloud service. The code block below adds two important scripts. The first adding the ability for the page to locate the associated Target cloud service and make the calls out to Adobe Target. The second is the addition of the cq.apps.targeting category.
The cq.apps.targeting category overrides the default cq/personalization/component/target component and uses the mobileapps/components/target component that renders offers specifically for mobile application consumption. More details of this will be discussed in the Target Component section.
The code should be added in the head.html and placed just before the end of the </head> element.
<div data-sly-test="${!wcmmode.disabled}">
<div data-sly-include="/libs/cq/cloudserviceconfigs/components/servicelibs/servicelibs.jsp" data-sly-unwrap></div>
<meta data-sly-call="${clientLib.all @ categories='cq.apps.targeting'}" data-sly-unwrap></meta>
</div>
body.html body-html
To enable the content author the ability to test different personas the body.html script needs to include the following code block as the first child of the body element.
<div data-sly-test="${!wcmmode.disabled}">
<div data-sly-resource="${'clientcontext' @ resourceType='cq/personalization/components/clientcontext_optimized'}" data-sly-unwrap></div>
</div>
The last bit of code required is at the very bottom of the body.html. This bit of code looks for the associated cloud service and injects the appropriate targeting engine code.
<div data-sly-test="${!wcmmode.disabled}">
<div data-sly-resource="${'cloudservices' @ resourceType='cq/cloudserviceconfigs/components/servicecomponents'}" data-sly-unwrap></div>
</div>
Reference Application reference-application
Examples of head.html and body.html can be found in the AEM Mobile Hybrid Reference Application showing the developer where to place the script blocks within the two scripts.
Content Sync Handlers content-sync-handlers
When the content author has finished creating content for the mobile application the next step is to download the source and build the application, or stage the content to be published. There are a number of steps that the developer is involved with to make this happen. To aid in rendering the content AEM Mobile utilizes content sync handlers to render and package the content. A new content sync handler has been introduced for the Personalization use case to render targeted content. The ‘mobileappoffers’ handler knows how to render the associated target offers that have been created by the content author. The mobileappoffers handler extends the abstract pages update handler therefore, many of the properties are similar. The details of the mobileappoffers handler has the following properties.
Target Component target-component
To help render content specifically for mobile applications, AEM Mobile uses the mobileapps/components/target component. The mobile target component extends the cq/personalization/components/target component and overrides the engine_tnt.jsp script. By overriding the engine_tnt.jsp this allows AEM Mobile to control the generated HTML for the mobile apps use case. For every component that is targeted by a content author, an associated mbox is created by the engine_tnt.jsp.
For each mbox an attribute of cq-targeting is added allowing application developers to write custom code to consume and use however they please. The AEM Mobile Hybrid Reference App has an example of a Angular directive that uses the cq-targeting attribute. The concept of content replacement when and how it is done is very much up to the mobile application developer. There is a Mobile SDK that is delivered via AEM /etc/clientlibs/mobileapps/js/mobileapps.js that provides an API to call the Adobe Targeting service. It is up to the application developer to specify when that call should be made according to the design of their application.