Requesting content

The SDK provides a simple API to request personalized content for your users in the form of promotions and recommendations. We represent promotions and recommendations in the SDK as ContentItem objects. Use the requestContentItemsWithContentOptions: selector to request content and pass in a block as a callback to handle the returned ContentItems:

[[MEDIOEVENT contentManager] requestContentItemsWithContentOptions:nil
    context:nil
    maxItems:1
    withBlock:^(NSArray *contentItems, NSError *e) {
        if (e == nil) {
            // request succeeded
            for (ContentItem *item in contentItems) {
                // process and display content items
            }
        }
        else {
            // request failed: handle error
        }
    }];

The context parameter is optional and it represents a specific page or view within your application for which you’re requesting content. You should pass nil as the context unless you have already configured a context with Medio.

Content request options

You can include a number of optional parameters as a ContentOptions object when requesting content. The fields that you specify in the ContentOptions object may influence the ContentItems that are returned. As an example, you can optionally specify a placement that represents a specific area within the page or view for which you’re requesting content. You should only specify a placement if you have already configured a placement with Medio. You can construct a ContentOptions object and specify a placement as follows:

ContentOptions* const contentOptions = [[[ContentOptions alloc] init] autorelease];
contentOptions.placements = [NSArray arrayWithObject:@"top"];

[[MEDIOEVENT contentManager] requestContentItemsWithContentOptions:nil
    context:nil
    maxItems:1
    withBlock:^(NSArray *contentItems, NSError *e) {
        ...
    }];

See the API Reference for a complete list of options that you can specify when requesting content.

Content presentations

Medio supports two different methods for presenting content: prescribed and native. These presentation methods define how your application should render each ContentItem. The presentation method is contained in the ContentItem.presentationMethod field.

Prescribed presentations

A presentationMethod value of PRESCRIBED indicates that your application should render the ContentItem according to a set of known templates. These templates define a set of fields in ContentItem.attributes that contain the actual content of an item for your application to render. You can use the value of the ContentItem.presentation field to determine what template the item is using and how to interpret the fields contained in ContentItem.attributes.

Presentation templates

Medio has a standard presentation template for promotions called “image_choice”. Applications using the image_choice template can use the following attributes in ContentItem.attributes to render the promotions:

  • handsetBannerPortraitUri: The URI of a 320×50 banner image to display on handsets in portrait orientation.
  • handsetBannerLandscapeUri: The URI of a 480×50 banner image to display on handsets in landscape orientation.
  • handsetInterstitialPortraitUri: The URI of a 320×480 interstitial image to display on handsets in portrait orientation.
  • handsetInterstitialLandscapeUri: The URI of a 480×320 interstitial image to display on handsets in landscape orientation.
  • largeInterstitialPortraitUri: The URI of a 640×960 interstitial image to display on large screen/tablet devices in portrait orientation.
  • largeInterstitialLandscapeUri: The URI of a 960×640 interstitial image to display on large screen/interstitial devices in landscape orientation.

At least one of the image URIs will be populated inside ContentItem.attributes. You should choose the best image to display based on:

  • Whether your application is running on a handset or a large screen/tablet device; and
  • Whether the device is in portrait or landscape orientation and what orientations your application supports.

As an example, you’d write the following code to handle ContentItems using a PRESCRIBED presentation method and the image_choice presentation:

[[MEDIOEVENT contentManager] requestContentItemsWithContentOptions:nil
    context:nil
    maxItems:1
    withBlock:^(NSArray *contentItems, NSError *e) {
        if (e == nil) {
            // success: handle content items
            for (ContentItem* item in contentItems) {
                if ([item.presentationMethod isEqualToString:@"PRESCRIBED"]) {
                    if ([item.presentation isEqualToString:@"image_choice"]) {
                        // choose the best image to display depending on
                        // device and orientation
                        NSString *banner320by50 = item.attributes[@"handsetBannerPortraitUri"];
                    }
                }
            }
        }
        else {
            // handle error
        }
    }];

Native presentations

A presentationMethod value of NATIVE indicates that your application should have specific knowledge about how to render the ContentItem and how to handle a user’s interaction with it. As an example, you may have a custom in-house promotion where the content for that promotion is contained within your application. Additionally, your application may contain all the logic about how to handle a user’s interaction with that promotion. ContentItems with a native presentation method may have attributes contained in the ContentItem.attributes field that contain additional metadata for your application.

Handling content impressions

When you display a ContentItem to a user of your application, you should log an impression event by passing the item into the logImpressionEvent: selector:

[MEDIOEVENT logImpressionEvent:item];

Handling clicks on content

The ContentItem.targetURI field specifies the destination that your application should take the user to when he/she clicks on the item. Depending on how you configure your promotion, the targetURI may contain a URI that your application knows how to interpret or it may contain an HTTP URL for a landing page.

The Medio Platform will automatically log clicks on ContentItems that have a PRESCRIBED presentation method. However, if you are using a NATIVE presentation method, your application should log a user’s click on a ContentItem by passing the item into the logClickEvent: selector:

[MEDIOEVENT logClickEvent:item];

Handling accepts and declines

Some promotions allow users to “accept” or “decline” some kind of offering. As an example, your shopping application may display a promotion for 10% off an order for users who take a survey. If a user decides to take the survey, he/she has “accepted” the promotion. You can log the user’s acceptance of your promotion by passing the ContentItem into the logAcceptEvent: selector:

[MEDIOEVENT logAcceptEvent:item];

If a user dismisses the promotion without taking the survey, he/she has “declined” the promotion. You can log the user’s decline of your promotion by passing the ContentItem into the logDeclineEvent: selector:

[MEDIOEVENT logDeclineEvent:item];