Upsight logo Back to top

Native Messaging

Overview


Native Messaging lets you leverage Upsight’s Segmentation and Targeting to deliver campaigns where you can implement your own native display, instead of using one of Upsight’s interstitial campaigns.

Note Native Messaging is supported on Upsight SDK versions 4.4.0 and above.

Native Messaging campaigns are delivered through Milestones and Billboards as with our other campaigns types, plus your own handling of the returned data. See the Milestones and Billboards section for the core concepts, and the below instructions for the additional steps required to start using Native Messaging.

Native Messaging campaigns are designed to create native experiences by collecting the inputs required to build a desired experience then sending that data to the correct devices at the correct times. Before a Native Messaging campaign is published, the application source code will need to be updated to handle and/or display the expected payload inputs. Once a campaign has been triggered and a payload has been passed back, it is up to the developer to have the infrastructure in place to handle and display their intended experience. This responsibility includes using Upsight provided helper methods and objects to track events such as clicks and impressions, as well as controlling the destruction of campaign content.

The Upsight SDK provides several methods to access the data contained in a payload and will return native objects when possible. These accessor methods are made available through USDataPayload objects. USDataPayload objects are an Upsight created object type with numerous Native Messaging specific capabilities. When a Native Messaging campaign is triggered, a USDataPayload object will be returned through a delegate method, where the developer can then access the contents of the USDataPayload object and build their experience.

Important Images are handled differently than the other supported data types. Images sent in a Native Messaging campaign are pre-fetched and stored on disk in order to reduce latency when rendering an image once a milestone is triggered. Pre-fetched images are accessed via a file path and can be handled in your source code using a USDataImage object along with the provided helper methods.

Integrate For Native Messaging


Receiving Data From a Native Messaging Campaign

In the source file in which you would like to access a Native Messaging payload, simply import UpsightKit.h.

 #import <UpsightKit.h>

Add the following delegate method to in order to access your Native Messaging payload. This method will get called when a campaign with a native message payload is received. While the billboard itself will not render any content, it is still used to make the payload available.

-(void)billboard:(id<USBillboard>)aBillboard didReceiveData:(id<USDataPayload>)aDataPayload {

 }

Accessing Content in a Native Messaging Campaign Object

USDataPayload objects provide instance methods to access the different types of objects contained in the native message.

Accessor method signatures for payloads generated using the Basic input format:

- (nullable NSString *)stringValueForKey:(nonnull NSString *)aKey;
- (nullable NSNumber *)booleanValueForKey:(nonnull NSString *)aKey;
- (nullable NSNumber *)intValueForKey:(nonnull NSString *)aKey;
- (nullable NSNumber *)floatValueForKey:(nonnull NSString *)aKey;
- (nullable UIColor *)colorValueForKey:(nonnull NSString *)aKey;
- (nullable USDataImage *)imageForKey:(nonnull NSString *)aKey;

USDataImage is an object defined in USDataPayload.h and contains properties for the image's loaded-on-disk file path, width, and height. Please use this information to load the image into memory and display it as you see fit.

Native Messages created using the ‘Raw’ input method will can be accessed via the getRawData method. This method provides a dictionary containing raw data in the same structure and format as entered in the campaign on the Upsight Dashboard.

- (nullable NSDictionary *)getRawData;

Important After the billboard containing the native message is dismissed, all data associated with the returned USDataPayload will be removed. For USDataImage objects, this means that the image on disk that is being referenced will be deleted. Please make a separate local copy of any images that you would like to persist past the life of the billboard.

Tracking User Interaction

Once the Native Messaging campaign is ready to be displayed to the user, the interaction the user has with the campaign can be tracked by calling various methods on your USDataPayload object. The available methods are:

  1. - (void)recordImpressionEvent; - Send this once the content of the campaign is rendered and displayed to the user.
  2. - (void)recordClickEvent; - Send this if the user interacts with your campaign such as accepting a dialog prompt.
  3. - (void)recordDismissedEvent; - Send this once the campaign is no longer on screen.
  4. - (void)destroy; - Send once the payload is no longer needed, e.g. after the dismiss button has been pressed or after a user has performed the desired action. This method must be called to inform the SDK that the content interaction is finished.

Important If a campaign is not intended to be seen by users, simply call destroy on the payload once it has been processed by the application.

Example


Here is a sample implementation of a Native Messaging campaign used to render a native interstitial within an application.

In order to have this example display the campaign on a device, a Native Messaging campaign was created on the dashboard by with the following inputs:

example screenshot 1

As well, to handle the expected payload from the Native Messaging campaign, the below implementation was added to the application intended to render the campaign:

- (void)billboard:(id<USBillboard>)aBillboard didReceiveData:(id<USDataPayload>)aDataPayload 
{
//Create USDataPayload object to access the data payload
USDataPayload *payload = (USDataPayload *)aDataPayload;

//Create a UIView to display the details contained in the USDataPayload object
UIView *contentDisplayView = [[UIView alloc]initWithFrame:CGRectMake(15, 450, 300, 150)];

//Add the body text to the display
UITextView *bodyCopy = [[UITextView alloc]initWithFrame:CGRectMake(40, 485, 120, 40)];
bodyCopy.text = [payload stringValueForKey:@"BodyCopy"];
[contentDisplayView addSubview:bodyCopy];

//Add a background color to the display
UIColor *backgroundColor = [payload colorValueForKey:@"BGColor"];
contentDisplayView.backgroundColor = backgroundColor;

//Pre-fetch and store images on disk to be accessed later through a file path
USDataImage * offerImage = [payload imageForKey:@"OfferImage"];
USDataImage * ornamentImage = [payload imageForKey:@"OrnamentImage"];

if(offerImage.imagePath && ornamentImage.imagePath) {
    //Retrieve images using file path and render in display
    UIImage *offerImageToRender = [UIImage imageWithContentsOfFile:offerImage.imagePath];
    UIImage *ornamentImageToRender = [UIImage imageWithContentsOfFile:ornamentImage.imagePath];
    if(offerImageToRender && ornamentImageToRender) {
        UIImageView *offerImageView = [[UIImageView alloc] initWithFrame:CGRectMake(215, 475, 100, 100)];
        offerImageView.image = offerImageToRender;
        UIImageView *ornamentImageView = [[UIImageView alloc] initWithFrame:CGRectMake(10, 580, 40, 40)];
        ornamentImageView.image = ornamentImageToRender;
        //Add imageViews to the display
        [contentDisplayView addSubview:offerImageView];
        [contentDisplayView addSubview:ornamentImageView];
    }
 }
if( nil != payload ) {
    [payload destroy];
 }
}

When a user reaches the appropriate milestone your Native Messaging payload will be delivered to the device. If handled correctly by the source code, the campaign creative will render an experience like this:

example screenshot 2

Testing a Native Messaging Campaign


Once a native messaging campaign is configured in the dashboard and the application is set up to handle native messaging payloads simply trigger a milestone with the scope of the campaign and open a billboard. Depending on the implementation, the campaign should render and, when clicked, a content displayed, dismissed, and click should display in Upsight RealTime.