Adobe Target VEC for Mobile Apps - Part 1 - Implementation
Published on 03/09/2019
11 min read
A walkthrough guide showing how to implement the new Adobe Target VEC extension from the SDK v5 using Adobe Launch for mobile applications
Hello everyone, Dan here and today I am going to take a look at the version 5 of the Adobe Experience Platform SDK for mobile applications.
There are many improvements in V5 from V4 but what I particularly want to look at is the use of the Visual Experience Composer in Adobe Target to create tests and personalisation within your mobile application.
Version 4 of the SDK did allow you to use Adobe Target but it was a case of using API calls and you couldn’t use the Visual Experience Composer. With V5, we can do use the Visual Experience Composer which should mean creating simple tests is actually really quick.
Before I start, there are a few tools that I’m going to use for this demo so I’ll quickly cover those off now so that you can follow along with this. The primary tool we’re going to use is Xcode which is used to build Swift applications – to caveat this, this demonstration is for iOS applications using Swift but if you’re building / have an Android application that’s built in object C, there is documentation around that and the process is almost identical to this but obviously the function calls are marginally different. So downloading Xcode is pretty simple, there is one thing to avoid here though – Xcode 11 beta has been released which you can download from Apple’s website. Do not do that as it uses a newer version of Swift and a lot of the things in this demo will not work! To download it, just go to the app store and search for Xcode (I already have it which is why it says open), and the version you are looking for is 10.3. This has the right version of Swift so everything will work. That will take quite a while to download as it’s rather large (around 6-7GBs).
When you have that, the second thing you’re going to want to download is a sample application so that we can implement Target in it and watch it working. The one I’m using in this demonstration is called the Luma app that is an app built by Adobe for demonstration purposes. This is the GIT repository for that application – I will post the full link to this in the transcript. If you just either clone it or download the zip file, that’s where we’ll start from. I already have this so to avoid you watching me download this (which would be very boring!) I’m just going to unzip it now from my downloads.
Once this is unzipped, there are two projects inside of it – lesson 1 and lesson 3. We’re going to use lesson 1 for this demonstration – if you use lesson 3 by mistake it will not work. Now that is unzipped, I’m going to move it to my desktop and open it. Inside this V5 sample app, you will see resources and inside that, lesson 1 and lesson 3, please use lesson 1. Let’s check this app works first – for this demonstration you do not need to be a mobile application developer or know Swift, you just need to follow these simple instructions and you’ll be able to get the Visual Experience Composer to work in your mobile application. The file you want to open is Luma.xcworkspace and this will open up the files in Xcode (you may get a warning like this to say it’s being downloaded from the internet, it’s fine!). Your Xcode will then open and the first thing to do is just to make sure that this application is working before we do anything to it. If we just click the play button, you’ll see that Xcode will start to build our Luma app for iPhone XR and it will launch a simulator. This can take a while so you may have to wait for this. You can see the progress in the top bar here so you can see currently it’s building 199 of 474. Once it’s built once, it’s then much quicker to build subsequently. Providing this builds correctly and launches, the next step that we will take is to open up Adobe Launch and configure a mobile property for us to use to configure the Target main extension and the Target VEC extension which we’ll then paste the correct code into our Luma application.
So we’ve now got the icon to say the build has succeeded and that will then give us a simulator, which is here. I have decided to use the iPhone XR but you do have the option to use any device that suits – it can be selected from this dropdown here. Again all iOS devices in this case and that’s what I’m using for the demo. Once this loads, it will launch our application and what we’ll be able to see if we just use this little icon here, is the debugger outputs of our application. We can now start to see the outputs of the app and we can see our application.
Once we have a working application, as I mentioned earlier the first thing to do here is to configure a Launch property for a mobile application and configure the right extensions. So let’s jump into that now and tick that off. So I’ll open Launch – I already have two properties here which are web properties which are my agency website and my agency website blog. We’ll create a new property using this button in the top right hand corner. We can call it anything we want – I’m going to call mine Optisights app. It will be a mobile property and it will default to privacy opted in which is fine for this example. We’ll use HTTPS and there’s nothing to configure in the advanced options so we’ll save this and then jump into our new property. We’ll go to extensions and you’ll see here that we’ve automatically got the mobile core extension and the profile extension, so there is no configuration for these two as they’re automatically configured with you client code, which in this case your Experience Cloud Org ID and then there’s nothing in profile. So what we need to do now is go to Catalogue, and there are two extensions for Adobe Target for a mobile property in Launch. We actually need both of them so we’ll start with the normal Adobe Target extension, client code is pulled in automatically and so we’ll save this and go back to Catalogue. In here, we’ll find the Adobe Target VEC extension and install that. Here we’ll get some options and the first is Auto-Fetch Target Activities. This has a blue box that explains that when this is turned on, the Target VEC activities are automatically fetched when the app is launched. So when the app is launched, all of the potential activities or tests or personalization that we’ve created in Target will be downloaded and cached to the app which is what we want so we’ll turn this on. Once we’ve turned this on, we’ll get a second option which is Fetch in the Background which means that when it is enabled, the Target VEC activity offers will be fetched in the background and cached without being applied to the current application screen. That’s if it’s turned on, so what that means is that it will fetch the activities due to the auto-fetch but it will do it in the background and it will not apply the changes to the app launch screen. If you have tests there, they will not work so we keep this off because for this demonstration we will be changing some content and offers on the launch page and we want those to render on initial launch of the application. We then save this and finally we’ll go back to the Catalogue and install the other extensions we may need for our mobile app. The first one is Adobe Analytics where I’ll pass my production report suite ID and save. The second is Adobe Audience Manager where no configuration is required so just click save. Now we have all of the extensions we need for our mobile app, we can then publish. We’ll add a new library and give it a name, select an environment, add all of the changes that we have made and then finally lick save and build for development.
Once this has built, we can now move on and implement the SDK into our application. If we go to the Environments tab and click the install icon, this will give us instructions for both Android and iOS, and object C and Swift so I will use iOS and Swift. This then gives us a list of instructions to install the SDK. The first thing you’ll see on here is that it says we’ll use CocoaPods to manage dependencies. If you have not got this installed on your machine, you’ll need it so if you click this link it will take you to the site and you can then use this line of code in your terminal to install it. This application manages the dependencies of your mobile application. Then there are a few instructions on here which we don’t actually need to follow as our application has already done them but we’ll cover them off anyway. The first one is “pod init” which creates a pod file if your application does not have one. Our application does already have a pod file so in the file tree here underneath pods, we already have a pod file so there’s no need to run this. Then we have this second section that if we copied it, these dependencies would need to be pasted into our pod file but again, our application already has those in there (note, it has a couple of extra ones that we don’t have which are other things the app is using). Then we have “pod repo update” and “pod install” – these would update any outdated dependencies or extensions, or “pod install” would actually install any we don’t have. In the case of the Luma application, they’re all contained within the folder we downloaded from GIT so there’s no need to do any of this. If we then move down to the “add initialization code”, you’ll see this first section has these import statements so if we copy these and paste them into places. The first one will be our AppDelegate file. If we scroll to the top, the Luma application already has these pasted here but we can paste them in again anyway and this will register the extensions that we need for the Experience Cloud SDK v5. So you’ve got the core, the Audience Manager analytics, normal Target, Target VEC and then the user profile. We’ve then got the actual line of code that configures Launch so if I move down, you’ll see here on lines 67-69 there is already these lines of code but we will override them and we’ll put in our code because it has our Launch configuration here. We then have the code that registers the extensions so again it’s a case of just copying them, go to where the extensions are already registered and then we just need to override those extensions like so.
Now at this point, we’ve actually installed the SDK within our application but there is another place we need to do it. So if we just save this and go to the home.swift file, which is the file that is used to render the view when the application launches, here we do exactly the same thing, which is we take the import statements and add them in here. Then there is one other thing that is done in this file that is quite crucial. In this section here lines 51-54, there is a function that is named “viewWillAppear” and this is an event which is emitted just before a view is rendered in our mobile application. Inside that, there is a call that is a “setTargetView” call and this sets the view of “HomeView” when the app is first launched. This needs to be done in home.swift. The other views within the application do not need to be manually registered. The mobile application and Target gets the lifecycle events emitted into the Target function automatically so every subsequent view that is made in the mobile app after this first one, the view is automatically passed to Target which will fire this function in the background which we’ll see working later on. So if we now save this, we are now in a position where we can launch our application (I’ll just clear the debugger) and we’ll launch using the play button in the top left hand corner. This can take a few minutes to build but our build has now succeeded.
Now we open our simulator and put these side by side and we’ll see that we’re starting to get our debug code. Now we want to check that the configuration of launch and the implementation of the SDK is working properly. First thing we want to validate is that the MID value which we can see all throughout the calls ending in 2175 (so this is the MID value initial request) is the same as the MID which is sent with the demdex call. So once we’ve searched MID, we’ll now search demdex and hit enter a few times. If you look at this part here, you’ll see that the MID is also set and it ends in 2175 which is the same. Couple of other things to validate – we can validate our orgID which is correct and we can also validate our launch code, where we can see here our actual launch code which you can’t see because it’s on my other screen but it matches my actual launch configuration. Finally, that the call to Adobe Target is working correctly so again if we just search in the debugger for TargetVEC and then just scroll up slightly, we should see all of the parameters here which are being passed to the mbox so we can see the Marketing Cloud Visitor ID which ends in 2175 which matches up with the other two values and you can see everything else that has been set (the context, the screen height, the width, colour depth, mobile platform etc). We could also pass other things into here so in any of the files, if we wanted to pass in customer values (something like order value), we could and it would pass with the mbox and we could use that to create audiences and Target personalised experiences but for the purpose of now, we’ll leave it as is.
Now we’re at this point and we’ve implemented the SDK and we’ve validated that everything is working, there is one final bit of set up we do in the application which is to configure the deep link. If we go to the file structure again, click the Luma app and as the default it says Luma Your-name so I’m going to set mine as Luma Dan and for Bundle Identifier, I’m going to set it as com.adobe.axp.dan and then finally, if you click the information tab this is where we set the deep link so if we scroll to the bottom, we’ll see URL types. You don’t really need to understand how this deep link works because your developer will have actually set it all up for you, you just need to know what the value is but if you are a developer, you’ll already understand this. So I’m going to set this URL_Schemes to lumadeeplink.dan, I’ll give this a save and I’ll just jump back into it to make sure it’s saved all my configuration which it has. Now what I want to do is reload my app so I’m going to completely delete the app that I have been using so far to get rid of the cache because caching can be a problem when you use the simulator so if you completely delete the application, it also gets rid of the data and the cache. And then if I just build this again the app will launch and we will see all of the debugger code as we did previously, but now we have our deep link configured. At this point, this is kind of where the implementation ends – there’s a lot more that you can do with it in terms of passing in custom parameters, using the API to do custom mbox calls but for the VEC implementation, this is it.
In the next section, I will be moving away from the implementation and looking at how you’d actually (as the Marketer) move forward and actually build tests in the Target interface that would then be served in your mobile application.