The iTunes Affiliate Program has two tools with similar names that allow publishers to create playlists inside the iTunes Store.  An iMix is a manually built playlist that is submitted to the store through the desktop iTunes application and has a static URL that can be affiliated. It is the ideal choice for a publisher who is nontechnical and plans to only create a small number of playlists.   A Web iMix is a tool that allows technically savvy publishers to dynamically generate playlists through a special URL. The Web iMix tool requires an account and is designed for creating many playlists dynamically or as a shopping cart. To learn more about the similarities of and differences between the two tools, see the iMix versus Web iMix blog entry.

Overview

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

Using the iTunes Store web iMix, 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.

Creating Web iMixes

To create a web iMix from iTunes Store content and display the results in an iTunes Store web iMix 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.com/webmix?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 web iMix, display the web iMix page, and allow users to purchase the web iMix content. The URL cannot refer to a predefined playlist.

When the iTunes Store receives the URL, it parses the data and displays your web iMix as a web iMix 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 web iMix in a single click, or add the web iMix content to a shopping cart to purchase at a later date. When users purchase your complete web iMix, 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 web iMix 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 web iMix page without the unavailable or unsupported content.
• Your web iMix 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 web iMix page and get the web iMix reference recognized as Affiliate Program revenue in the iTunes Store.

Obtaining Your Affiliate Token

Before you can create a web iMix from iTunes Store content and display the results in a web iMix page, you must first send your Affiliate Program Publisher token to your Apple Technical Representative.

Apple and Affiliate Program Providers use this token to determine the Affiliate Program revenue corresponding to specific purchases in the iTunes Store.

Obtaining your Affiliate Program Publisher token depends on your Affiliate Program Provider. For example: Linkshare (US, JP, CA), DGM (AU, NZ) or TradeDoubler (Europe).

For Linkshare:

1. Go to http://www.linkshare.com.
2. Log in to your affiliate account.
3. Navigate to the Apple iTunes Create Links page.
4. Select the Banners / Images link option.
5. Scroll to the first banner. Your token is the 11-digit encrypted affiliate identifier displayed as the value of the id parameter in the "Code for Link" text box.
6. Copy your token and send it to your Apple Technical Representative. Your token is case sensitive so be sure to copy it exactly as it appears in the "Code for Link" text box.

For DGM:

1. Go to http://www.dgmpro.com.
2. Log in to your affiliate account.
3. Click the "my details" tab.
4. Scroll to the Company ID field. Your token, usually five or six digits in length, is the company account identifier displayed as the value of the Company ID field.
5. Copy your token and send it to your Apple Technical Representative.

For TradeDoubler:

Go to http://www.tradedoubler.com. Log in to your affiliate account. Click the "settings" tab on the menu on the left and then click "site information." Copy your program ID and website ID and send it to your local Affiliate Manager at itunesaffiliates@euro.apple.com in an email entitled "Affiliate Token."

Defining Your URL Content Request

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

Parameter Key	Description	Required	Values
title	The string containing the title you want to use for your web iMix. iTunes displays the title in your web iMix page in the iTunes Store. For example: My+first+mix.	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 web iMix. iTunes displays the description in your web iMix 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 web iMix 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 web iMix page in the iTunes Store. For example: 78922868,148120908,257676472,215304964.	Y	A comma-separated list of 1 to 26 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 web iMix 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 web iMix page.	N	true, false The 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 web iMix 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 at http://gtools.org/tool/md5-hash-generator/. 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 web iMix title or description, use an encoded [q] character. For example, if you want your web iMix 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 web iMix URL as an example: http://itunes.com/webmix?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 web iMix URL becomes: http://itunes.com/webmix?desc=Made+For+You&ids=78922868,148120908&stripUnpurchasable=true&title=My+Mix&wdId=1001&key=e7c10bc7f4000ece45d854abc1211e59.

Web iMix and Explicit Content

Web iMix follows 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 web iMix page for those fields.

In addition, web iMix follows any established iTunes parental controls. For example, if "Restrict explicit content" is set in the Parental pane in iTunes, web iMix disables explicit content in your web iMix page.

Web iMix Examples

The following are examples of fully-qualified, authenticated URLs for specific iTunes Store web iMixes, using "Regent Street" as the shared secret:

• In the following example, the web developer, 1001, sends an authenticated web iMix 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.com/webmix?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 web iMix 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.com/webmix?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 web iMix 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 web iMix page track list:

  http://itunes.com/webmix?desc=The+best%21&ids=2001698,284871485,259658354&stripUnpurchasable=true&title=Greatest+Hits&wdId=1001&key=e9bec2ffcb37bcbba12e6d308e7eb9c7

Web iMix 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.com/webmix?' + sorted_encoded_query_str + '&key=' + hs
        HashMe.print_result(string_to_hash, hs)
        puts "\nWebIMix url: #{url}"
    end
end

HashMe.run