How to use the Adobe Target form composer in a Mobile App

The last article reviewed the (recently deprecated) VEC extension, with a view to getting your optimisation and personalisation activities up and running very quickly with. As with any optimisation programme, starting with simple tests that attack low hanging fruit is a great way to quickly prove the value of your work. Due to the minimal implementation effort involved, the visual editor was a good option to deliver those results fast but there were some fairly clear technical limitations.

Similarly, as you work through the ideas in your test backlog, you will inevitably start focusing on hypotheses that call for more complex changes, which adjust the layout of components or even involve a complete re-design of a particular app view. This is where Target’s form composer comes into play, and this article will guide you through some ideas to help you get started. At risk of stating the obvious, the form composer isn’t only for more complex tests, it’s also a great option for delivering tests that you might have previously designed using the visual editor.

The screenshots below are from an iOS (Swift) implementation but, as per the previous articles, all of the steps are broadly the same regardless of which platform/language you are working with.

#1 Understanding your test backlog

This is the most important part of the implementation phase — in order for there to be any chance of Target delivering value, it is absolutely crucial that business and technical stakeholders are very closely aligned.

The visual editor had a pre-defined list of actions that you could use to make changes, which meant you didn’t need to plan what you wanted to test — what you tested was largely determined by the limitations of the editor. However, the form composer removes those obstacles, which means two things:
i) the scope of what you can change is now limited by the apps ability to handle different json structures (i.e.the Target offer code)
ii) you must have a clear idea of the activities you want to run, so that the development work can take place that ensures your app can deliver them.

The easiest way to think about this is to look at the design of the variant(s) in your test(s) and identify which components in the existing app will either have changes applied or don’t currently exist. To illustrate that point we will quickly jump to the end of the process and think about what the end result should look like.

In the example below, the variant (right) that I will test in my activity has the following requirements:
i) a sale banner is inserted
ii) the CTA colour is changed
iii) the bus icon is changed
iv) the headline copy is changed
v) the offer text is changed

All of these requirements need to be communicated to the development team, so that they can start to plan out how the app will handle this new information. Taking my example above, I’d then expect questions around whether the banner is one image or if I intend to supply the component parts (i.e. colour, text, image etc) which the app will then transform into a banner; similarly, I’d expect to agree rules around how long the copy changes can be and the size requirements for the icon that the bus will be replaced with.

The frequency of your app release cycles will play a part in just how far down the line you need to plan, as well as other factors like the availability of development resources and where this sort of work sits on the priority list. Having said that, I like the fact that this sort of project forces stakeholders to plan and anticipate what the next 3–6 months of testing will look like, because having a well thought out roadmap significantly increases the chances of your optimisation programme delivering value.

#2 Sending a request to Target

I’m assuming that your Launch configuration is in place by this point but if that’s not the case then head back to the first article to see how that’s done. Whilst not quite as simple as the VEC implementation, the steps required to send a request to Target are still very straightforward.

First you need to import the ACPTarget library and register the extension in your AppDelegate file:

The next step is to construct the component parts of the request that you’re going to send to Target and then execute that request. In the screenshot below I have empty placeholders for things like mbox parameters and order confirmation attributes (we’ll cover those shortly) but it should give you a clear idea of how the request is structured.

It’s worth mentioning that a callback is triggered when Target responds with offer data, so you will need to develop a method to handle the data that’s available in the response. In the example above you can see that a function called applyOffer will be executed when the callback is made.

I won’t go through the detail of the function in this post because exactly how this is done will depend on how your app is built and the tests that you want to run. However, thinking back to my requirements in section 1, it should be clear that applyOffer has to be able to handle: a sale banner image, a CTA colour, a bus icon, headline copy and some offer text. The screenshot below shows how applyOffer starts off by handling the response from Target, by assigning each value in my json structure to its own variable.

From there it’s just a question of applying each of those variables to the relevant element in the app. For all of the existing elements this is fairly straightforward but I’m also inserting a banner element that doesn’t exist in the current app, so how does that work?

In my sample app, I have created a placeholder element which isn’t visible but, when the “bannerimage” key exists in my Target offer, the image is inserted into that placeholder and the element is made visible. This example should help bring into focus what I talked about in section 1 i.e. why it’s so important to have a clear test roadmap, so you can provide detailed requirements to your development team.

#3 Validate Target request/response

It would make sense to build your app at this point to make sure that the requests are being sent. If you check in your debug console you should see an entry that states “Target request was sent with url” with your mbox name listed against the “name” key:

Finally, if you continue to scroll further down the debug statements then you should eventually see an entry confirming “Target response was received”. At this point, with no activity or offer content set up in Target, there’s not too much to see, so the main thing to check is that you have a response status of 200:

#4 Adding additional parameters

Earlier I mentioned the placeholders that I’d created for additional parameters that can be included in the request. I won’t explain mbox & profile parameters because the help docs cover those here but it’s worth briefly covering a couple of the others:
i) ACPTargetProduct
Create entity parameters that can be used for Recommendations

ii) ACPTargetOrder
Create order confirmation mbox parameters — for those familiar with Target web implementations, this should look familiar

iii) ACPTargetParameters
Create a parameters object that combines the various parameter types, so that they can be passed to Target via the request

Again, it’s worth building your app at this point to make sure that the additional parameters are being included in the request that’s being sent. In the screenshot below you can see “loyaltytier” in the main “parameters” object, the “order” and “product” objects, as well as my “preferredTripType” property in the “profileParameters” object.

There’s still not too much to see at this point, in terms of the response from Target, but it’s worth checking that you’re getting that 200 response status:

#5 Create a Form activity

The activity creation steps are more straightforward than creating an activity with the visual editor — by this point most of the hard work has been done, it’s just a question of adding your agreed JSON structure(s) to your offer(s). Once you’ve chosen which type of activity you are creating, you then need to select “Mobile App” and “Form” before clicking “Next”.

The second step is to choose which “location” (i.e. mbox) you want to serve your activity from — I’m using the “booking-view-mbox” which is created when my Booking View screen begins to load.

The final part of the activity creation is to create a JSON offer that will be returned when Target sends a “booking-view-mbox” request on the Booking View screen. During the development phase you will be adjusting the structure but once you’re in production this shouldn’t be any more complicated than a copy & paste exercise.

Although the visual editor is now deprecated, in my previous article I went through the final two steps of activity creation (Targeting and Goals & Settings) in section #4, so I won’t go through those again here.

#6 Launch activity

We’re now at the point where the activity is ready to be launched, which means that you’ll also want to validate that the activity is working correctly. Again, I mentioned a couple of QA options in the previous article, so I won’t cover those again here.

The screenshot above is a nice representation of the component parts that go into a project like this: working out the business requirements (i.e. what you want to test) and then translating them into a technical solution that your app can deliver, with JSON in the middle glueing everything together.

Summary

I hope this was a useful introduction on how you can increase the value you get out of Target in your mobile app by removing the technical constraints of the visual editor. The increased flexibility of this JSON approach means that your testing programme can continue to mature; for companies that use AEM it also provides a great opportunity to build your content and then share those fragments with Target so they can be consumed as part of your activity configuration.

I’ll end by re-iterating what was mentioned in section #1 — this sort of project can only be successful with the right business and technical stakeholders involved and aligned. Think about your test roadmap and how that should evolve over a 3–6 month period, in order to ensure the app can continue to support your optimisation programme as it matures.