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 ContentAPI.getContentItems method to request content and pass in an anonymous implementation of ContentListener as a callback to handle the returned ContentItems:

ContentAPI.getContentItems(null, null, 1, new ContentListener() {
            @Override
            public void contentItemsReceiver(List items, StatusCode status) {
                if (status.equals(StatusCode.OK)) {
                    // request succeeded
                    for (ContentItem item : items) {
                        // 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 null 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.Builder cb = new ContentOptions.build();
cb.addPlacement("top");

ContentAPI.getContentItems(null, cb.build(), 1, new ContentListener() {
            @Override
            public void contentItemsReceiver(List items, StatusCode status) {
                ...
            }
        });

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 returned by the ContentItem.getPresentationMethod method.

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 returned by ContentItem.getAttributes that contain the actual content of an item for your application to render. You can use the value of the ContentItem.getPresentation method to determine what template the item is using and how to interpret the fields returned by ContentItem.getAttributes.

Presentation templates

Medio has a standard presentation template for promotions called “image_choice”. Applications using the image_choice template can use the following attributes returned by ContentItem.getAttributes 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 in the Map returned by ContentItem.getAttributes. 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:

ContentAPI.getContentItems(null, null, 1, new ContentListener() {
            @Override
            public void contentItemsReceiver(List items, StatusCode status) {
                if (status.equals(StatusCode.OK)) {
                    // request succeeded
                    for (ContentItem item : items) {
                        if ("PRESCRIBED".equals(item.getPresentationMethod())) {
                            if ("image_choice".equals(item.getPresentation())) {
                                String banner320by50 = item.getAttributes().get("handsetBannerPortraitUri");
                            }
                        }
                    }
                }
                else {
                    // request failed: 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 returned by ContentItem.getAttributes 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 EventAPI.logImpressionEvent method:

EventAPI.logImpressionEvent(item);

Handling clicks on content

The ContentItem.getTargetURI method returns 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 ContentItem.getTargetURI method may return a URI that your application knows how to interpret or it may return 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 EventAPI.logClickEvent method:

EventAPI.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 EventAPI.logAcceptEvent method:

EventAPI.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 EventAPI.logDeclineEvent method:

EventAPI.logDeclineEvent(item);