Overview

The iTunes Store Collection (formerly Web iMix) allows you to link from your website to Collections you dynamically create from randomly selected content in the iTunes Store. You can create a variety of Collections using iTunes Store content; including songs, albums, music videos, TV episodes, and movies.

Using the iTunes Store Collection, you can feature a playlist on your website and allow users to buy individual items or the complete playlist directly from iTunes by simply clicking a link in your website.

Requesting Access

To request a Collection account please submit a request at the Affiliate Helpdesk

Collection Builder

Use the Collection Builder tool available at http://collection.itunes.apple.com to easily create your own Collections.

Remember to add your affiliate token in the ‘at’ parameter to your Collection output link and earn commission.

A correctly affiliated link will look like the following:
https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewWebIMix?desc=The%20best%20song&ids=695318301&title=My%20Collection&wdId=134440&ct=&at=PHGAffiliateToken&key=525fd5f12a381e2b8c88f5633ec0a216

You can also add optional campaign tracking by adding text to the ‘ct’ parameter.

Update for PHG

If you already have a Collection account no change is needed to your account. All you need to do is append your PHG affiliate token to the end your existing or newly created Collection link.

Here is an example Collection link with the PHG affiliate token attached:
http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewWebIMix?
desc=iMix&ids=78922868&stripUnpurchasable=true&title=My+Mix&wdId=1001&key=e7c10bc7f4000ece45d854abc1211e59&at=PHGAffiliateToken

Creating Collections

To create a Collection from iTunes Store content and display the results in an iTunes Store Collection page, you must create a link in your website that passes a fully-qualified, authenticated URL content request to the iTunes Store.

The fully-qualified, authenticated URL must have the following format:

http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewWebIMix?parameterkeyvalue

Where parameterkeyvalue can be one or more parameter key and value pairs indicating the details of your request.

To construct a parameter key and value pair, you must concatenate each parameter key with an equal sign (=) and a value string. For example: key1=value1. To create a string of parameter key and value pairs, you must concatenate each pair, in ascending alphabetical order, using an ampersand (&). For example:

key1=value1&key2=value2&key3=value3

The URL must contain all the necessary data to create the Collection, display the Collection page, and allow users to purchase the Collection content. The URL cannot refer to a predefined playlist.

When the iTunes Store receives the URL, it parses the data and displays your Collection as a Collection page in the iTunes Store, including title, description, cover art, pricing information, buy buttons, total number of items, and a track list containing content referenced in the URL’s ids parameter.

Depending on the specific content contained in your URL request, users can purchase individual tracks or your entire Collection in a single click, or add the Collection content to a shopping cart to purchase at a later date. When users purchase your complete Collection, iTunes creates a playlist in the users’ iTunes Library, using the title specified in the URL.

Notes:
  • When the iTunes Store parses your data and displays your Collection page, it displays the best quality and purchase options for each item specified in your URL (for example, HD before SD).
  • The iTunes Store might not be able to display all content referenced in your URL due to regional restrictions, availability issues, or unsupported content. If this occurs, the iTunes Store creates your Collection page without the unavailable or unsupported content.
  • Your Collection does not appear in iTunes Store searches.
  • Your total URL string can be no more than 2000 characters in length. If your URL is longer than 2000 characters, the iTunes Store returns an error message and rejects the URL.
  • Your URL, and all parameter keys and values, are case-sensitive.
  • It is critical to generate your URLs correctly in order to display your Collection page and get the Collection reference recognized as Affiliate Program revenue in the iTunes Store.
Requesting a Collection Account

Before you can create a Collection from iTunes Store content and display the results in a Collection page, you must first request a Collection Account

Defining Your URL Content Request

The following table defines the parameter keys and values you can specify to create your Collection and view the Collection page in the iTunes Store:

Parameter Key Description Required Values
title The string containing the title you want to use for your Collection. iTunes displays the title in your Collection page in the iTunes Store.For example: My+first+collection. Y A URL-encoded, or percent-encoded, text string no more than 100 UTF-8 characters in length, after unencoding.The text string is restricted to the following characters:

  • Alphanumerics
  • Hyphens (-)
  • Underscores (_)
  • Commas (,)
  • Periods (.)
  • Colons (:)
  • Apostrophes (‘)
  • Exclamation points (!)
  • Commercial at / At sign (@)
  • Left and right parenthesis ()
  • Left and right brackets []
desc The string containing the description you want to use for your Collection. iTunes displays the description in your Collection page in the iTunes Store.For example: A+selection+of+hits+handpicked+for+you. Y A URL-encoded, or percent-encoded, text string no more than 400 UTF-8 characters in length, after unencoding.The text string is restricted to the following characters:

  • Alphanumerics
  • Hyphens (-)
  • Underscores (_)
  • Commas (,)
  • Periods (.)
  • Colons (:)
  • Apostrophes (‘)
  • Exclamation points (!)
  • Commercial at / At sign (@)
  • Left and right parenthesis ()
  • Left and right brackets []

To include a line break in your description text, use and encoded [br] character. For example, if you want your Collection to display the following two-line description:

These are the greatest hits.
Songs for a winter day.

Send iTunes the following desc parameter key and value: &desc=These+are+the+greatest+hits.+Songs+for+a+winter+day.

ids The list of content to be presented in your Collection page in the iTunes Store.For example: 78922868,148120908,257676472,215304964. Y A comma-separated list of 1 to 99 iTunes IDs.To obtain iTunes Adam IDs you can use:

  • The iTunes Store Web Service Search API. For more information, see the iTunes Store Web Service Search API documentation.
  • The iTunes Enterprise Partner Feed. For more information, see the iTunes Enterprise Partner Feed documentation.

For copies, contact your Apple Technical Representative.

stripUnpurchasable A flag indicating whether or not you want to remove the following items from your web iMix page:

  • Items not available for individual purchase (for example, album-only tracks and album-only music videos)
  • Albums not available for one-click purchasing
  • Movies available only for rent

If you specify stripUnpurchasable=true, the iTunes Store removes all items matching any of the above criteria from your Collection page track list. The iTunes Store displays the Buy All button in your web iMix page.

If you do not specify this parameter, or specify stripUnpurchasable=false, the iTunes Store displays all items specified in your URL, but does not display pricing information and buy buttons for the items that are not directly purchasable in the track list. If the track list contains any item that is not directly purchasable, the iTunes Store does not display the Buy All button in your Collection page.

N true, falseThe default is false.
wdId The web developer identifier you want to send to the iTunes Store.For example: 1001.

The iTunes Store uses this parameter to identify the creator of the URL and verify that the developer has access to create and send a Collection to the iTunes Store. In addition, the iTunes Store uses the parameter for security, reporting, and affiliate revenue requirements.

Y A numeric value provided by your Apple Technical Representative.Do not send any Affiliate Program identity or token information separately in the URL. Apple stores all necessary Affiliate Program information within the wdId parameter and associated databases.
key An MD5 hash of the URL request string and a shared secret. The key is used to verify the integrity of the URL (ensuring that the URL was created by the specified web developer and that the URL was not modified after creation). A MD5 hash encoder can be found athttp://www.md5hashgenerator.com.For example: b1d2d291eb55082e270b5c672d55eae5.

Note: Your Apple Technical Representative supplies the shared secret. Only you and Apple should have access to the shared secret and hashing algorithm, be sure to store the information in a secure location.

Y A text string containing the MD5 hash of the URL request string (parameter keys sorted in ascending alphabetical order) and a shared secret.For information on how to create your key paramater, see “Creating Your Key Parameter” later in this document.
Notes:

Due to hashing issues with Internet Explorer, you should not use the following characters in your title and desc parameter strings:

  • Quotation marks (“)
  • New line (\n)
  • Left and right angle brackets (< and >)
  • Question marks (?)
  • Ampersands (&)

To validate hashing, you should test your URL on a variety of browsers (for example, Safari, Internet Explorer, Firefox, Opera). If you encounter any problems, remove any strange characters from your title and desc parameter strings and try again.

To include a quotation mark (“) in your Collection title or description, use an encoded [q] character. For example, if you want your Collection to display the following in your description: Click on the ”Buy” button to purchase. Send iTunes the following desc parameter key and value: &desc=Click+on+the+%5Bq%5DBuy%5Bq%5D+button+to+purchase.

Creating Your Key Parameter

Using the following Collection URL as an example: http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewWebIMix?title=My+Mix&desc=Made+For+You&ids=78922868,148120908&stripUnpurchasable=true&wdId=1001.

To create your key parameter:

  1. Take the URL request string, excluding everything up to and including the question mark (?). For this example, the URL request string is “title=My+Mix&desc=Made+For+You&ids=78922868,148120908&stripUnpurchasable=true&wdId=1001”.
  2. Sort the parameter keys in ascending alphabetical order. For this example, the resulting string becomes: “desc=Made+For+You&ids=78922868,148120908&stripUnpurchasable=true&title=My+Mix&wdId=1001”.
  3. Perform a URLDecode on the string from step 2. For this example, the resulting value becomes: “desc=Made For You&ids=78922868,148120908&stripUnpurchasable=true&title=My Mix&wdId=1001”.
  4. Append the shared secret to the string from step 3, using a colon (:) as a separator. For example, using the following values:
    • Shared secret = “Regent Street”
    • String from step 3 = “desc=Made For You&ids=78922868,148120908&stripUnpurchasable=true&title=My Mix&wdId=1001”
    • The resulting string becomes: “desc=Made For You&ids=78922868,148120908&stripUnpurchasable=true&title=My Mix&wdId=1001:Regent Street”.
  5. Perform an MD5 hash on the result from step 4. For this example, the resulting key parameter value becomes: e7c10bc7f4000ece45d854abc1211e59.
  6. Append the key parameter and its value from step 5 to the URL parameters from step 2.The resulting Collection URL becomes: http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewWebIMix?desc=Made+For+You&ids=78922868,148120908&stripUnpurchasable=true&title=My+Mix&wdId=1001&key=e7c10bc7f4000ece45d854abc1211e59.

Collections and Explicit Content

Collections follow the standard iTunes censoring guidelines for the imported title and description parameters. For example, if the title or description string contains text that should be censored, the iTunes Store removes the entire title or description and displays nothing in your Collection page for those fields.

In addition, Collections follow any established iTunes parental controls. For example, if “Restrict explicit content” is set in the Parental pane in iTunes, Collection disables explicit content in your Collection page.

Collection Examples

The following are examples of fully-qualified, authenticated URLs for specific iTunes Store Collections, using “Regent Street” as the shared secret:

  • In the following example, the web developer, 1001, sends an authenticated Collection URL for a playlist called “My first mix”, with a description of “A selection of hits handpicked for you”, and containing four items from the iTunes Store:http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewWebIMix?desc=A+selection+of+hits+handpicked+for+you&ids=78922868,148120908,257676472,215304964&title=My+first+mix&wdId=1001&key=2cd63c149155a9f148548156dda2087d
  • In the following example, the web developer, 55, sends an authenticated Collection URL for a playlist called “Bare essentials”, with a description of “As simple as it gets”, and containing a single item from the iTunes Store:http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewWebIMix?desc=As+simple+as+it+gets&ids=257676472&title=Bare%20essentials&wdId=55&key=9086be78cb8e56929835d6561fad91c1
  • In the following example, the web developer, 1001, sends an authenticated Collection URL for a playlist called “Greatest Hits”, with a description of “The best!”, containing three items from the iTunes Store, and specifying that the iTunes Store should remove all items the user cannot purchase from the Collection page track list:http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewWebIMix?desc=The+best%21&ids=2001698,284871485,259658354&stripUnpurchasable=true&title=Greatest+Hits&wdId=1001&key=e9bec2ffcb37bcbba12e6d308e7eb9c7

Collection Sample Key Script

For an example of how to generate your key parameter value, see the following sample script implementation:

#!/usr/bin/ruby

require 'digest/md5'
require 'uri'

class HashMe
    def self.generate_hash(hash_input)
        md5hash = Digest::MD5.new
         md5hash.update(hash_input)
         md5hash.hexdigest
    end

    def self.ask(prompt)
        print prompt, ' '
        $stdout.flush
        s = gets
        s.chomp!
    end

    def self.print_result(hash_input, hash_string)
        puts "\nMD5 hash of [#{hash_input}]: #{hash_string}";
    end

    def self.sort_parameters(parameter_str)
        parameter_str.split(/&/).sort.join("&")
    end

    def self.run
        encoded_query_str = HashMe.ask("Enter the url encoded query string (example: \ ids=2001698,59950847&title=My+Hits&desc=My+Mix+Rocks.&wdId=1007):\n")

        sorted_encoded_query_str = HashMe.sort_parameters(encoded_query_str)

        unencoded_query_string = URI.unescape(sorted_encoded_query_str)

        pp = HashMe.ask("\nEnter pass phrase (example: mac12flyingcow):\n")
        string_to_hash = unencoded_query_string + ':' + pp

        hs = HashMe.generate_hash(string_to_hash)
        url = 'http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewWebIMix?' + sorted_encoded_query_str + '&key=' + hs
        HashMe.print_result(string_to_hash, hs)
        puts "\nWebIMix url: #{url}"
    end
end

HashMe.run