Working with Previews

[Skip TOC]

Table of Contents

Feature Overview

New Terms

Changes to the Existing Preview Feature

Configuration

Watermarking Configuration

Preview Configuration

Content Submission

Using the Developer Portal

Using the Content Aggregator Interface

Preview Management

In the Developer Portal

In the Catalog Manager

In the Vending Manager

Customization

Content Management API

Subscriber API

Integration

Subscriber Access

Device-Based Previews

PC-Based Previews

Feature Overview

Previews enable subscribers to sample content before purchasing. The enhanced preview feature provided by this update includes the following improvements to the existing preview feature:

• A content item can have multiple preview files. However, the default implementation of the Subscriber Portal makes only the first file available to subscribers for ring tone previews.
• Preview files can be of any MIME type defined to the Content Delivery Server, but cannot be a type of content that requires more than one source file such as a MIDlet or iAppli application.
• Image previews can be watermarked when stocked by the Vending Manager administrator, when viewed by the subscriber, or both when stocked and viewed.
• The original content file can be used as a preview file for content types that do not require more than one source file.
• Content that has editions can have different previews for each edition. The preview files for an edition are contained in a preview set. Preview sets can be shared by multiple editions.
• Optional captions can be used to identify the previews available. A default caption can be set for use when no caption is provided.

Subscribers can preview items from the content details when browsing available content. Subscribers see or hear the previews that are associated with the edition that runs on their device. Capability matching is done only on the edition, not on the preview file. The only checking done by the system is to ensure that the preview file is of a MIME type that is supported by the Content Delivery Server. The Content Delivery Server does not check whether the subscriber is using a browser that is capable of showing or playing the selected preview.

Note: This update replaces the existing preview feature with an enhanced preview feature. The Content Delivery Server manuals are not included in this product update. The information in this supplement to the documentation overrides the information in the manuals as noted in the following sections.

[Top]

New Terms

Preview

A means for a subscriber to sample a content item, for example a few notes of a ring tone, a sample image, or one or more sample images for a game.

Preview File

A file that contains a sample of a content item. The content file itself can also be used as a preview file. Preview files that are available in various formats for each content type enable subscribers to sample a content item on a web browser or a WAP browser. The preview file must be of a MIME type that is supported by the Content Delivery Server and cannot be an application or other type of content that requires more than one source file. A preview file can be a local file, an externally hosted file, or a copyrighted externally hosted file.

Preview Caption

A label that is given to a preview file for identification. The preview caption is what the administrators and subscribers see when working with the preview files. A caption is optional. If no caption is provided, the default implementation of the Subscriber Portal uses "Untitled" as the caption.

Preview Set

One or more preview files that are associated with a content edition. When a new edition or an edition update is submitted, it can be associated with the preview set of an existing edition or new preview files can be submitted with the edition to create a new preview set.

Preview Position

The position in which a preview file appears in a preview set. The preview position determines the order of the preview files in the list shown to the subscriber.

Watermarking

A means of applying a watermark as defined by a set of watermarking attributes that are specified in a configuration file. The watermark can be applied when the content is stocked, when the preview is viewed by the subscriber, or both when stocked and viewed by the subscriber, depending on how the Content Delivery Server is configured. For this release of the Content Delivery Server, watermarks are applied only to image preview files.

[Top]

Changes to the Existing Preview Feature

The following table describe the differences introduced with this product update.

[Top]

Configuration

Before submitting preview files, decide whether you want to add watermarks to previews, which content types can use the original content file as a preview file, and which MIME types are treated as audio preview files. Watermarking configuration is done by the system administrator. Preview configuration is done by the Catalog Manager administrator and the system administrator.

[Top]

Watermarking Configuration

Watermarking is the process of modifying a file to mark it as sample content. In the Content Delivery Server, a watermark can be applied when content is stocked and when content is previewed by a subscriber. Watermarks are cumulative. If a watermark is applied when content is stocked and another watermark is applied when a preview is accessed by a subscriber, the preview contains both watermarks.

The Catalog Manager administrator works with the original preview file. If the Content Delivery Server is configured to watermark content when content is stocked, the watermarked version of the preview file is stored in the Vending Manager and is available to the Vending Manager administrator. If the Content Delivery Server is configured to watermark content when a preview is accessed, only the subscriber sees the watermarked version.

Watermarking is not enabled by default. To enable watermarking, follow the instructions in the following sections. The watermarking utility provided with the Content Deliver Server can watermark only files with the following MIME types:

• image/png
• image/jpg
• image/gif
• image/tiff

The default watermark is the string "Sample" in the center of the image as shown in the following figure.

In this release, watermarks are supported for images only. Animated images cannot be watermarked. Externally hosted preview files that are copyrighted can be watermarked only when content is previewed, not when content is stocked. If the file is not copyrighted and the system is configured to watermark files when content is stocked, a copy of the externally hosted file is watermarked and stored in the Content Delivery Server.

Watermarking When Content is Stocked

To enable watermarking when content is stocked, set the watermarking.enabled.content-types property in the $CDS_HOME/deployment/deployment-name/conf/StockingWatermarking.properties file to the content types to which watermarks are applied. The default is image. In this release, watermarks are supported for images only.

To use the default watermarking implementation for image content, do not change the other properties in this file.

You can use text, an image, or both text and an image as your watermark. Set the properties in the $CDS_HOME/deployment/deployment-name/conf/StockingWatermarkingImage.properties file to define the watermark to use. These properties are described in the following table.

Properties for Defining a Watermark

The server does not need to be restarted if you make changes to either of the property files. If you change the properties in the $CDS_HOME/deployment/deployment-name/conf/StockingWatermarkingImage.properties file, preview files for content stocked after the change use the updated watermark. Preview files for content stocked before the change retain the original watermark until one of the following actions occurs:

• Content is unstocked and then stocked again.
• Content is unpublished and then published again.
• An edition is updated or added to a content item.
• A preview set is changed by adding a file, deleting a file, changing a caption, or reordering the files.
• A custom preview set is created for an edition.

When one of the listed actions occurs for a content item, all preview files associated with that item are recreated using the original file and the updated watermark.

If the preview file is hosted externally, a watermarked copy of the file is stored in the Content Delivery Server. If the externally hosted preview file is updated, a copy of the updated file is watermarked and stored in the Content Delivery Server the next time a subscriber purchases or downloads an edition with which the preview file is associated.

Watermarking When Content is Previewed

To enable watermarking when content is previewed by the subscriber, set the watermarking.enabled.content-types property in the $CDS_HOME/deployment/deployment-name/conf/DiscoveryWatermarking.properties file to the content types to which watermarks are applied. The default is an empty string, so no watermark is applied when content is previewed.

To use the default watermarking implementation for image content, do not change the other properties in this file.

You can use text, an image, or both text and an image as a watermark. Set the properties in the $CDS_HOME/deployment/deployment-name/conf/DiscoveryWatermarkingImage.properties to define the watermark to use. These properties are described in the table Properties for Defining a Watermark. If watermarking is also enabled when content is stocked, the preview contains both watermarks.

The Content Delivery Server provides an implementation of the Content Management API that handles watermarking as described in this section. To customize the watermarking process for your enterprise, you need to create your own implementation of the Content Management API. See Content Management API for information.

The server does not need to be restarted if you make changes to either of the property files. If you change the properties in the $CDS_HOME/deployment/deployment-name/conf/DiscoveryWatermarkingImage.properties file, the next time a subscriber previews content the updated watermark is used.

[Top]

Preview Configuration

Preview configuration consists of the following tasks:

• Setting up the use of the content file as a preview file
• Identifying audio preview files
• Setting the default caption

Setting up the Use of the Content File as a Preview File

For some content types, such as image, the original content file can be used as the preview, if desired. For other types of content, such as midlet, the original content file is not suitable for use as a preview. The Catalog Manager administrator can specify the content types for which the content file can be used as a preview file. If the option to use the content file as a preview file is selected when content is submitted, two copies of the file are kept by the Content Delivery Server. One copy is stored as the original content file and the other copy is stored as a preview file.

To enable or disable the use of the content file as the preview, follow these steps:

1. Start the Catalog Manager administration console.
    
2. Click Content in the main menu bar.
    
3. Click the MIME Types tab.
    
4. Click the content type that you want to work with.

   Do not choose midlet or iappli. These types of content cannot be used as preview files.

5. Choose whether the content file can be used as a preview file.

   Select Submitted Content of this Type Can Be Used as Its Own Preview to enable the content file to be used as a preview file. Remove the check from the box if you do not want to allow the content file to be used as a preview file.

6. Click Done.
    

Identifying Audio Preview Files

To ensure that the Content Delivery Server correctly recognizes files as audio previews, edit the AudioMimeTypes.config file in the $CDS_HOME/deployment/deployment-name/conf directory. Enter one or more regular expressions as defined by the java.util.regex package to identify the MIME types used in your system for audio files. Enter one expression per line, for example:

audio/.*
sound/.*
application/x-ert

Setting the Default Caption

A preview caption is optional. If no caption is provided by the content provider or the administrator, a default caption is used. To set the default caption, set the desktop.preview.untitled property in the $CDS_HOME/deployment/deployment-name/conf/SubscriberPortalLocaleResource.properties file to the string of your choice. If you do not want a default caption, set this property to the empty string. If you have locale-specific resource files, set the property in the files for the locales that you use.

[Top]

Content Submission

Content is submitted to the Content Delivery Server using either the Developer Portal or the Content Aggregator Interface. An item of content has one or more editions. Each edition can have different capabilities that are used to determine the devices on which it runs. Preview files are submitted with editions. Preview files can be of any MIME type supported by the Content Delivery Server, but should be of a type that is supported by the device for which the associated edition is targeted. If the preview file cannot be handled by the device, the subscriber is unable to preview the content. In addition to submitting previews for use with wireless access protocol (WAP) browsers on devices, you can also submit previews for use with web browsers for subscribers who use the PC-based Subscriber Portal.

[Top]

Using the Developer Portal

You can submit content using the Developer Portal component of the Content Delivery Server. The submission wizard supports submission of a single item of content as well as submission of multiple items in a Zip or provisioning archive (PAR) file. A PAR file cannot be used to submit preview files with content.

See the Content Developer Guide in the $CDS_HOME/Documentation directory for complete instructions for submitting content. The following sections correspond to sections in that guide and supplement the existing information:

• Submitting New Content with the Wizard
• Submitting Content Editions with the Wizard
• Creating a Content Submission File
• Examples of Content Submission Files with Preview Files

Submitting New Content with the Wizard (page 6)

After completing Step 5, select Use Original Content as a Preview if you want the content file to also be a preview file. A caption is optional. This option is available only if the Catalog Manager administrator enabled the option for the type of content that you are submitting.

In Step 7, the following fields are no longer available:

• Preview
• Screen Shot #1
• Screen Shot #2  

In Step 9, after the section for entering pricing information is a section for submitting one or more preview files. If you chose to use the original content as a preview, the file appears in both the WAP Previews list and the Web Previews list. To submit preview files, follow these steps:

1. Indicate whether the preview file is local or remote.

   Select File if the preview file is local. Select URL if the preview file is remote.

2. Enter the fully qualified name of the file or the URL to the file, or click Browse to locate the file.
    
3. Select the type of browser for which the preview file is used.

   Select WAP to use the file when subscribers browse from their device. Select WEB to use the file when subscribers browse from their PC. Both targets can be selected.

4. Click Add.

   A window is shown while the add operation is performed. If the file is invalid, the window shows an error. Otherwise, the window closes and the preview file is added to the WAP Previews list and the Web Previews list based on the choices made in Step 3.

5. (Optional) Enter a caption, if desired.

   If the preview file is for both WAP and web browsers, entering a caption for the file in the WAP Previews list automatically enters the same caption for that file in the Web Previews list. If you want a different caption for the web preview file, overwrite the caption in the Web Previews list. This action breaks the link between the two captions. Captions appear in both the device-based and PC-based Subscriber Portal. If no caption is provided, the default implementation shows Untitled.

6. (Optional) To verify that you have the correct file, click Inspect to view or hear the preview.
    
7. For additional preview files, repeat Step 1 through Step 6.

   The preview files that you submit create the preview set for the first edition of this item of content.

8. (Optional) If you have more than one preview file, use the up and down arrows for each item to set the order in which they are presented to the subscriber.
    
9. (Optional) To remove a file from the list, click Delete for that item.

Also in Step 9, the section for specifying device capabilities has changed. To let the Content Delivery Server determine which devices can run the content, select Use Automated Capabilities Matching (typical). To choose devices or set specific capabilities, select Use Custom Capabilities Matching and make your choices as described in the Content Developer Guide. Additional fields are hidden until Use Custom Capabilities Matching is selected.

Submitting Content Editions with the Wizard (page 10)

After completing Step 5, select Use Original Content as a Preview if you want the content file to also be a preview file. This option is available only if the Catalog Manager administrator enabled the option for the type of content that you are submitting. A caption is optional.

In Step 7, after the section for entering content information is a section for associating preview files with the edition. You can use the same preview files that are used for other editions of this content or you can submit new preview files.

• To create a new preview set for this edition, follow these steps:
   
1. Select Use a Custom Set of Preview Files.
    
2. Choose the files that you want to use.

   To submit new files, follow Step 1 through Step 9 in "Submitting New Content with the Wizard."

   To use files in other preview sets, follow these steps:

   1. Click Available Editions.

      The Select from Available Editions window is shown.

   2. Select from the Filter list the preview set that contains the file that you want to use.

      The entries in the list identify the edition and the preview set that it references. If all editions use the same preview set, the list contains only one entry. If more than one edition uses the same preview set, the set appears in the list more than once. If an edition has been updated, all versions of the edition appear in the list. The WAP Files and Web Files lists are filled with the preview files in the selected preview set.

   3. Select the file or files that you want to use.

      Click Inspect to view or hear the preview.

   4. Specify the target for each selected file.

      Select WAP to use the file when subscribers browse from their device. Select WEB to use the file when subscribers browse from their PC. Both targets can be selected.

   5. Click Add.

      The files that you selected are added to the WAP Previews and Web Previews lists on the Content Descriptions page based on the targets for each selected file.

   6. (Optional) Repeat Step 2b through Step 2e to select additional files for this edition.

      When you are done selecting files, click Cancel in the Select from Available Editions window.

   7. On the Content Descriptions page, edit the caption, change the position of the files in the list, or delete files as needed.
   
    
• To use an existing preview set, select Use an Existing Set of Preview Files and select the preview set from the drop-down list.

  The entries in the list identify the edition and the preview set that it references. If all editions use the same preview set, the list contains only one entry. If more than one edition uses the same preview set, the set appears in the list more than once. If an edition does not have any preview files, the set is shown as Empty Set. If an edition has been updated, all versions of the edition appear in the list. The files in the selected preview set are added to the WAP Previews and Web Previews lists. If the empty set is selected, no files are added to the lists. To view a preview file, click Inspect for that item.

In Step 8, the section for specifying device capabilities has changed. To let the Content Delivery Server determine which devices can run the content, select Use Automated Capabilities Matching (typical). To choose devices or set specific capabilities, select Use Custom Capabilities Matching and make your choices as described in the Content Developer Guide. Additional fields are hidden until Use Custom Capabilities Matching is selected.

Creating a Content Submission File (page 24)

You can submit multiple items of content of the same content type in either a Zip or PAR file. To submit preview files with content, you must use a Zip file. The content submission file describes the content that you are submitting. In the "Content Descriptor Section" (page 25), new tags are added after the <Version> tag. The following elements describe the preview files that you want to submit:

• To submit preview files with the content, use the following statements:

  <Preview>     
    <Wap>         
      <File src="path" caption="caption"/>
    </Wap>
    <Web> 
      <File src="path" caption="caption"/>
    </Web>
  </Preview> 

  Files under the <Wap> tag are used when subscribers are using the device-based Subscriber Portal. Files under the <Web> tag are used when subscribers are using the PC-based Subscriber Portal. If you do not want to provide preview files for a target, do not include the tags for that target in the file. The value specified for src must be the fully qualified file name of a file within the package or the URL that points to the file, for example, src="/graphics/image1.jpg" or src="http://test.server/image1.jpg". A caption is optional.

  Provide one <File> tag for each preview file that you have. To use the content file as a preview file, use the following statement:

  <File useContentFile="true" caption="caption"/>

• To use an existing preview set, use the following statement:

  <Preview useEditionName="edition-name"/>

  edition-name is the name of the edition whose preview set you want to use. This option is valid only if you are adding or updating an edition.

• If no <Preview> tag is provided, the action taken is dependent on the value specified for the <Action> tag.

  If the action is New, it is assumed that the content has no preview files. If the action is Add or Update, the preview set used by the edition named by the <EditionName> tag is used. If the edition named by the <EditionName> tag has preview files and you want to submit an edition that does not have preview files, use the following statement:

  <Preview none="true"/>

In the "Web Descriptor Section" (page 28), the following tags under the <WebGroup> tag are no longer used and are ignored if present:

• <Preview src="path"/>
   
• <ScreenShot src="path"/>

In the section "Sample Content Submission Files" (page 31) the following sample submission file replaces Code Example 5. This sample includes two previews that are available when using a WAP browser on the device-based Subscriber Portal and one preview that is available when using a web browser on the PC-based Subscriber Portal. Of the two files targeted for a WAP browser, one is the content file itself and one is a different version of the content. The file targeted for the web browser is the content file itself.

Content Submission File for New Ring Tone Content

<?xml version="1.0" encoding="UTF-8"?>
<ContentSubmission>
  <Action value="New"/>
  <ContentDescriptor>
    <ContentType>ringtone</ContentType>
    <EditionName>Lullaby</EditionName>
    <Version>1.0</Version>
    <Preview>
      <Wap>
        <File useContentFile="true" caption="Full Version"/> 
        <File src="/preview/LullabySample.au" caption="Short Version"/>
      </Wap>
      <Web>
        <File useContentFile="true" caption=""/> 
      </Web>
    </Preview>
  </ContentDescriptor>
  <WebDescriptor>
    <Category>Home:Entertainment:Music</Category>
    <DeveloperContentId>12345</DeveloperContentId>
    <WebGroup>
      <DisplayName>Lullaby</DisplayName>
      <ShortDescription>Latest from GenCompany</ShortDescription>
      <LongDescription>Bring back memories of gentler days
        every time your phone rings</LongDescription>
    </WebGroup>
  </WebDescriptor>
</ContentSubmission>
  

Examples of Content Submission Files with Preview Files

The following examples show the use of the <Preview> element for different submission scenarios. Each example is followed by a description of the contents of the Zip file that the sample content submission file describes.

Content Item Using the Original Content as a Preview

<?xml version="1.0" encoding="UTF-8"?>
<ContentSubmission>    
  <Action value="New"/>
  <ContentDescriptor>
    <ContentType>ringtone</ContentType>
    <EditionName>Lullaby1.1</EditionName>
    <Version>1.1</Version>
    <Preview>
      <Wap>
        <File useContentFile="true" caption="Full Version"/>
      </Wap>
      <Web>
        <File useContentFile="true" caption="Hear the complete lullaby"/>
      </Web>
    </Preview>
  </ContentDescriptor>
  <WebDescriptor>
    <Category>Home:Entertainment:Music</Category>
    <WebGroup>
      <DisplayName>Lullaby</DisplayName>
      <ShortDescription>Memories every time your phone rings</ShortDescription>
      <LongDescription>Bring back memories of gentler days every time your phone rings</LongDescription>
    </WebGroup>
  </WebDescriptor>
</ContentSubmission>  

The Zip file contains the following files:

• Lullaby_1_1.mid
• meta/ContentSubmission.xml

Edition Using the Original Content as a Preview and a Different Preview for the Web

<?xml version="1.0" encoding="UTF-8"?>
<ContentSubmission>
  <Action value="Add">
    <EditionName>Lullaby1.1</EditionName>
  </Action>
  <ContentDescriptor>
    <ContentType>ringtone</ContentType>
    <EditionName>Lullaby1.2</EditionName>
    <Version>1.2</Version>
    <Preview>
      <Wap>
        <File useContentFile="true" caption="Full Version"/>
      </Wap>
      <Web>
        <File src="/preview/Lullaby_1_2.mp3" caption="Full Version"/>
      </Web>
    </Preview>
  </ContentDescriptor>
</ContentSubmission>

The Zip file contains the following files:

• Lullaby_1_2.mid
• meta/ContentSubmission.xml
• preview/Lullaby_1_2.mp3

Content item with a preview using a separate file as the preview

<?xml version="1.0" encoding="UTF-8"?>
<ContentSubmission>
  <Action value="New"/>
  <ContentDescriptor>
    <ContentType>ringtone</ContentType>
    <EditionName>Lullaby2.1</EditionName>
    <Version>2.1</Version>
    <Preview>
      <Wap>
        <File src="/preview/LullabySample_2_1_Short.mid" caption="Short Version"/>
      </Wap>
      <Web>
        <File src="/preview/LullabySample_2_1_Short.mid" caption="Hear a short version of the lullaby"/>
      </Web>
    </Preview>
  </ContentDescriptor>
  <WebDescriptor>
    <Category>Home:Entertainment:Music</Category>
    <WebGroup>
      <DisplayName>Lullaby</DisplayName>
      <ShortDescription>Memories every time your phone rings</ShortDescription>
      <LongDescription>Bring back memories of gentler days every time your phone rings</LongDescription>
    </WebGroup>
  </WebDescriptor>
</ContentSubmission>

The Zip file contains the following files:

• Lullaby_2_1.mid
• meta/ContentSubmission.xml
• preview/Lullaby_2_1_Short.mid

Edition with a Preview Using a Separate File as the Preview and a Different Preview for the Web

<?xml version="1.0" encoding="UTF-8"?>
<ContentSubmission>
  <Action value="Add">
    <EditionName>Lullaby2.1</EditionName>
  </Action>
  <ContentDescriptor>
    <ContentType>ringtone</ContentType>
    <EditionName>Lullaby2.2</EditionName>
    <Version>2.2</Version>
    <Preview>
      <Wap>
        <File src="/preview/LullabySample_2_2_Short.mid" caption="Short Version"/>
      </Wap>
      <Web>
        <File src="/preview/LullabySample_2_2_Short.mp3" caption="Short Version"/>
      </Web>
    </Preview>
  </ContentDescriptor>
</ContentSubmission>

The Zip file contains the following files:

• Lullaby_2_2.mid
• meta/ContentSubmission.xml
• preview/Lullaby_2_2_Short.mid
• preview/Lullaby_2_2_Short.mp3

Content Item with Multiple Previews

<?xml version="1.0" encoding="UTF-8"?>
<ContentSubmission>
  <Action value="New"/>
  <ContentDescriptor>
    <ContentType>midlet</ContentType>
    <EditionName>GreatGame3.1</EditionName>
    <Version>3.1</Version>
    <Preview>
      <Wap>
        <File src="/preview/GreatGameTitle.jpg" caption="Title Screen"/>
        <File src="/preview/GreatGamePlay.jpg" caption="Play Screen"/>
      </Wap>
      <Web>
        <File src="/preview/GreatGameTitle.jpg" caption="Title Screen"/>
        <File src="/preview/GreatGamePlay.jpg" caption="Play Screen"/>
      </Web>
    </Preview>
  </ContentDescriptor>
  <WebDescriptor>
    <Category>Home:Entertainment:Games</Category>
    <WebGroup>
      <DisplayName>Great Game</DisplayName>
      <ShortDescription>Play a great game</ShortDescription>
      <LongDescription>Have a great time playing a great game</LongDescription>
    </WebGroup>
  </WebDescriptor>
</ContentSubmission>

The Zip file contains the following files:

• GreatGame_3_1.jad
• GreatGame_3_1.jar
• meta/ContentSubmission.xml
• preview/GreatGameTitle.jpg
• preview/GreatGamePlay.jpg

Edition with Multiple Previews

<?xml version="1.0" encoding="UTF-8"?>
<ContentSubmission>
  <Action value="Add">
    <EditionName>GreatGame3.1</EditionName>
  </Action>
  <ContentDescriptor>
    <ContentType>ringtone</ContentType>
    <EditionName>GreatGame3.2</EditionName>
    <Version>3.2</Version>
    <Preview>
      <Wap>
        <File src="/preview/GreatGameTitle.jpg" caption="Title Screen"/>
        <File src="/preview/GreatGamePlay.jpg" caption="Play Screen"/>
      </Wap>
      <Web>
        <File src="/preview/GreatGameTitle.gif" caption="Title Screen"/>
        <File src="/preview/GreatGamePlayAnimated.gif" caption="Animated Play Screen"/>
      </Web>
    </Preview>
  </ContentDescriptor>
</ContentSubmission>

The Zip file contains the following files:

• GreatGame_3_2.jad
• GreatGame_3_2.jar
• meta/ContentSubmission.xml
• preview/GreatGameTitle.jpg
• preview/GreatGamePlay.jpg
• preview/GreatGameTitle.gif
• preview/GreatGamePlayAnimated.gif

Using the Content Aggregator Interface

The changes described in "Creating a Content Submission File" also apply to the submission file used to submit content using the Content Aggregator Interface. If authentication is needed to access a preview file, it must be the same as the authentication specified for the content file. See the Content Developer Guide in the $CDS_HOME/Documentation directory for complete instructions.

[Top]

Preview Management

Preview sets can be edited in the Developer Portal by the content provider and in the Catalog Manager administration console by the administrator. Vending Manager administrators can only view preview sets.

You can manage the preview sets associated with an item of content independent of the editions, or you can manage the preview set associated with a specific edition. When managed independently, any change to a preview set affects all editions that reference that preview set. When managed by edition, the following options are available:

• Use a different existing preview set.
• Create a new preview set.

If changes are made so that a preview set is no longer referenced by any edition, that preview set is automatically deleted by the system.

Note: To inspect preview files while managing preview sets, your browser must be set to allow popups for the Content Delivery Server Developer Portal, Catalog Manager administration console, and Vending Manager administration console. Also, the Content Delivery Server does not check whether the browser being used is capable of showing or playing the selected preview. The browser determines how unsupported file types are handled.

[Top]

In the Developer Portal

Preview sets can be edited only for content or editions that have a status of New or Denied. To edit preview sets in the Developer Portal, follow these steps:

1. Log in to the Developer Portal.
    
2. Click the Content List tab to show the list of submitted content.
    
3. Click the title of the content that you want to edit.

   The Content Properties page is shown. A section that contains the preview information is shown after the Catalog Description section.

4. To edit preview sets independently of editions, follow these steps:
    
1. Select the preview set that you want to edit from the Select a Preview Set list.

   If the content has a status of New or Denied, all preview sets can be edited. If the content has a status of Published or Unpublished, a preview set can be edited if the set is associated with only new editions or edition updates with a status of New or Denied.

2. Click Edit Set.

   The Edit Preview Set page is shown. The editions that use the preview set are identified below the name of the set. On this page, modify the preview set as described for creating a new preview set when submitting an edition in "Submitting Content Editions with the Wizard." You can also change captions, reorder the files, and delete unwanted files. To view or hear a preview file, click Inspect for that file.

3. After you have made your changes to the preview set, click OK.

   All editions that use the preview set are affected by the changes made. If the content had a status of Denied, the status for the content and all its editions is changed to New. If the content had a status of Published or Unpublished, the following changes occur:

   • The status for all new editions or edition updates that had a status of Denied and that use the modified preview set is changed to New.
   • The status for the content and all other editions is unchanged.
      
5. To edit the preview set for a specific edition with the status of New or Denied, follow these steps:
    
1. In the Editions section of the Content Properties page, click the name of the edition that you want to edit.  

   The View Content Edition page is shown. After the General Information section is the Previews section.

2. Click Edit Edition Previews.

   The Edit Edition Previews page is shown. The editions that use the preview set are identified below the name of the set. On this page you can modify the preview set using the same process used when submitting editions (see "Submitting Content Editions with the Wizard.") You can also change captions, reorder the files, and delete unwanted files. To view or hear a preview file, click Inspect for that file.

3. After you have made your changes to the preview set, click OK.

   If this edition was using a preview set that other editions used, a new preview set is created for this edition. Other editions remain unchanged. If the content had a status of Denied, the status for the content and all its editions is changed to New. If the content had a status of Published or Unpublished and the edition had the status Denied, the status of the edition is changed to New. No other editions are changed.

[Top]

In the Catalog Manager

To edit preview sets in the Catalog Manager administration console, follow these steps:

1. Log in to the Catalog Manager administration console.
    
2. Navigate to the content that you want to edit.
    
3. Click the title of the content that you want to edit.

   The View Content Properties page is shown. A section that contains the preview information is shown after the Catalog Description section. This information replaces the Preview, Screen Shot #1, and Screen Shot #2 fields shown previously.

4. To edit preview sets independently of editions, follow these steps:
    
1. Select the preview set that you want to edit from the Select a Preview Set list.
    
2. Click Edit Set.

   The Edit Preview Set page is shown. The editions that use the preview set are identified below the name of the set. On this page, modify the preview set as described for creating a new preview set when submitting and edition in "Submitting Content Editions with the Wizard." You can also change captions, reorder the files, and delete unwanted files. To view or hear a preview file, click Inspect for that file.

3. After you have made your changes to the preview set, click OK.

   All editions that use the preview set are affected by the changes made.

5. To edit the preview set for a specific edition, follow these steps:
    
1. In the Editions section of the View Content Properties page, click the name of an original edition that you want to edit.  

   The View Content Edition page is shown. After the General Information section is the Previews section.

2. Click Edit Edition Previews.

   The Edit Edition Previews page is shown. The editions that use the preview set are identified below the name of the set. On this page you can modify the preview set using the same process used when submitting editions (see "Submitting Content Editions with the Wizard.") You can also change captions, reorder the files, and delete unwanted files. To view or hear a preview file, click Inspect for that file.

3. After you have made your changes to the preview set, click OK.

   If this edition was using a preview set that other editions used, a new preview set is created for this edition. Other editions remain unchanged.

[Top]

In the Vending Manager

To view preview sets in the Vending Manager administration console, follow these steps:

1. Log in to the Vending Manager administration console.
    
2. Navigate to the content that you want to view.

   Previews for content accessed from the Catalog tab are not watermarked. Previews for content accessed from the Stocked Content are watermarked if the Content Delivery Server is configured to watermark items when content is stocked.

3. Click the title of the content that you want to view.

   The View Content Properties page is shown. A section that contains the preview information is shown after the Catalog Description section.

4. To view preview sets independently of editions, select the preview set that you want to view from the Select a Preview Set list.

   To view or hear a preview file, click Inspect for that file.

5. To view the preview set for a specific edition, click the Edition ID of the edition that you want to view.  

   The View Content Edition page is shown. After the General Information section is the Previews section. To view or hear a preview file, click Inspect for that file.

[Top]

Customization

The Content Management API and the Subscriber API have been changed to support the enhanced preview feature. If you have your own implementation of the ContentManager interface or you have created your own Subscriber Portal, review the following information to determine what changes you need to make.

See the Customization Guide in the $CDS_HOME/Documentation directory for complete information on the APIs discussed in the following sections. These sections correspond to sections in that guide and supplement the existing information.

[Top]

Chapter 4, Content Management API

One of the uses of the Content Delivery Server Content Management API is to alter the content binaries or the content information at the time that content is sent to the Subscriber Portal. This API provides methods that you can implement to perform such tasks as adding digital rights management code or applying a watermark.

If the implementation provided by the Content Delivery Server meets your needs and you do not need to do any additional manipulation or validation of the content at the time it is presented to the subscriber, you do not need to create your own implementation of this API. If you have your own implementation of this API and you do not need to work with previews or apply a watermark at the time content is previewed, you do not need to make any changes to your existing code.

The following classes are new:

• ContentPreview - Provides methods for getting and setting the properties and the binary of a preview file.
• MimeType - Provides methods for getting and setting properties of the MIME type associated with a preview file.

The following classes are changed:

• ContentConstants - Includes the constant KEY_CONTENT_PREVIEWS that is used to get the collection of preview files.
• ContentInfo - Includes the methods getValue and setValue that are used to get and set content properties based on the key specified.

See the output from the Javadoc™ tool in the $CDS_HOME/javadoc/cdsapi directory for details on the new and changed classes.

The getContentInfo method of the ContentManager interface is called when the subscriber requests the details of a content item and when the subscriber previews the content in the Subscriber Portal. To watermark or alter the preview files in any way, follow these steps:

1. Make sure that the binary for the preview file is available for watermarking.

   If you are using the default Subscriber Portal, the binary for the preview file is available when the subscriber previews the content.

   If you use your own version of the Subscriber Portal that was written using the Subscriber API, the call to IContentService.getContentDetails(), ContentHandler.getContentDetails(), or ContentHandler.GetContentDetailsList() must include the flag for returning resource binaries. See Subscriber API for more information.

2. Implement the getContentInfo method to perform the following steps:
    
1. Use the ContentInfo.getValue method with the KEY_CONTENT_PREVIEWS key to get the original collection of ContentPreview objects in the ContentInfo object that is created by the Content Delivery Server.

   Each ContentPreview object represents one preview file. If the content item has no preview files, the method returns an empty collection. If neither the flag for returning resource binaries nor the flag for returning resource URLs was included when the content details were requested from the Subscriber Portal, the method returns null.

2. For each ContentPreview object in the collection, modify as needed using the getter and setter methods for the properties.
    
3. Use the ContentInfo.setValue method with the KEY_CONTENT_PREVIEWS key to save the collection of modified ContentPreview objects in the ContentInfo object that is returned to the Content Delivery Server.

The getContentInfos method of the ContentManager interface is called when the subscriber requests information on a list of items in a category. If you want to watermark all of the preview files for all of the items in the list at this time, follow the steps in this section for each item in the list returned.

[Top]

Chapter 10, Subscriber API

The Subscriber API provides access to data maintained by the Content Delivery Server. If you have written your own client application that accesses the Subscriber API directly, see the output from the Javadoc tool in the $CDS_HOME/javadoc/subscriberapi directory for information on the following changes:

• IContentService has new constants that are used to access preview files.
• IContentDetails has two new methods, getPreviews() and getPreviews(int target), that return a collection of IContentPreview objects. The methods for getting Preview, ScreenShot1URL, and ScreenShot2URL are deprecated.
• IContentPreview is a new class that contains the information about a preview file.
• IMimeType is a new class that contains information about the MIME type of a preview file.

If you have written your own client application that accesses the Subscriber API through the XML-RPC implementation, review the information in this section to determine if you need to make changes to your application. This information supplements the information in Section 10.3 " XML-RPC Implementation," in the Customization Guide.

Preview files are accessed through the content object, which is accessed using the getContentDetails() and getContentDetailsList() methods of the ContentHandler class. The following table describes the changes to the parameters referenced by these methods. The information for each parameter in this table overrides the information in Table 10-9 in the Customization Guide.

Integration

New pages have been added to the device-specific user interface framework to support the enhanced preview feature. This section describes these pages and how they are used. See the Integration Guide in the $CDS_HOME/Documentation directory for complete information on the framework.

Section 7.1.1, "Page Definitions," describes the files that contain the page definitions for the device-based Subscriber Portal. The following page definitions are new:

• _preview.xml. Shows the preview if it is an image or plays the preview if it is an audio file. For an audio file, the page shows a link for replaying the preview.
• _preview_list.xml. Shows a list of previews if more than one is available. The previews are identified by either the caption supplied by the content provider or Catalog Administrator or by a default caption if no caption was supplied.

Note: If the first of multiple preview files is an audio file, the _preview.xml page is used and only the first file is available to the subscriber.

Section 7.1.3.2, "View Content Process" describes the process for viewing content. In Step 3, the Purchase Content page contains a Preview link if a preview is available for the content. When the Preview link is clicked, one of the following actions is taken:

• If only one preview is available or if the first preview is an audio file, the Preview page, generated from _preview.xml, is shown. For an image preview, this page shows the image. For an audio preview, this page plays the audio file and shows a link for replaying the preview. For both image and audio, this page has a link to either purchase or download the content, depending on whether the subscriber has previously purchased the item.
   
• If multiple previews are available, the list of previews, generated from _preview_list.xml, is shown. When a preview is selected, the Preview page is shown as described in the previous bullet.

If you created a style sheet that you used to generate a set of customized pages, run the command /bin/cdsi genmarkup -ss stylesheet where stylesheet is the name of your style sheet to generate an updated set of pages that includes the new pages. If you customize the new pages, run the command /bin/cdsi genmarkup -ss all to update the pages for all devices as described in Section 7.3, "Modifying Pages for All Devices."

[Top]

Subscriber Access

The Content Delivery Server provides a device-based Subscriber Portal and a PC-based Subscriber Portal. Subscribers can preview content using either version. The following sections describe how subscribers access previews using these portals.

Device-Based Previews

Previews are available from the Purchase Content page. The Purchase Content page is shown when a subscriber selects a content item. If the item has a preview file, one of the following links is shown after the Purchase link:

• Preview - Shown for previews that are image files
• Listen - Shown for previews that are audio files

The link shown is based on the type of file provided as the preview, not on the type of content with which the preview is associated.

If only one image preview file is available, that image is shown in the browser when the subscriber clicks Preview. If more than one image preview file is available, a list of links to the files is shown. The files are shown in the order in which they appear in the preview set. If a caption was provided by the content provider or Catalog Manager administrator, it is used as the link text. If a caption was not provided, the default caption is used. To view a preview, click the caption.

If the preview is an audio file, that file is played when the subscriber clicks Listen. If more than one audio preview file is available, only the first file is played.

The Content Delivery Server does not check whether the browser being used is capable of showing or playing the selected preview. The browser determines how unsupported file types are handled. Also, preview presentations are best handled by browsers that support XHTML. For browsers that support WML, page definitions in the device-specific user interface framework must be customized to handle audio previews. The device-specific user interface framework is described in the Integration Guide.

[Top]

PC-Based Previews

Previews are available from the list of available content and from the Content Details page. If a preview is available for a content item, one of the following buttons is shown next to the name of the item on the list of available content and above the Tell a Friend button on the Content Details page:

• Preview Content - Shown for previews that are images
• Listen - Shown for previews that are audio files

The link shown is based on the type of file provided as the preview, not on the type of content with which the preview is associated.

When Preview Content is clicked, all available image preview files are shown with their caption. If no caption was provided, the default caption is shown. When Listen is clicked, the audio preview file is played in an embedded player window. If more than one audio preview file is available, only the first file is played.

The Content Delivery Server does not check whether the browser being used is capable of showing or playing the selected preview. The browser determines how unsupported file types are handled.

[Top

Copyright © 2006 Sun Microsystems, Inc. All rights reserved. Use subject to license terms.