Advanced Linking

The first part of this document is intended for partner publishers that need to create partner tracking to be added to raw links provided by the advance linking tools. This information is primarily for tech savvy partners who need to automate the creation of many links.

The second part of this document, “Using Partner Links Inside Apps,” is intended for partners that need to create partner tracking links that will be implemented inside an app. The aim of this structure is to enhance the user experience on mobile devices. It will enable the user to go directly from an app to the iTunes Store or the App Store without first opening the web browser app. It is not recommended to use this method for website integrations as it limits reporting.

Note: The easiest and most direct way to create a partner tracking link is to use the Link Maker tool found inside your partner network’s dashboard for the iTunes and App Store Partner Program.

Table of Contents

Adding Partner Tracking

Properly built partner links are essential for proper integration into the partner program. Adding partner tracking to raw iTunes links is necessary to fully use the advanced linking tools such as the Search API and the EPF, for linking to special pages inside iTunes and the App Store, and for working with links that deal with promotions.

The partner program relies on four separate partner networks for programs worldwide. Because each program has a proprietary methodology for building links, this document includes a section for each.

Partner Encoding for PHG

To create a partner tracking link for PHG all you need to do is use the parameter “at” and your Partner ID

Correct tracking examples:
https://itunes.apple.com/us/album/random-access-memories/id617154241?at=123456

For more information on creating links for PHG view the Basic Partner Link Guidelines for the PHG Network

Understanding Links

While understanding how to convert a raw link into a partner link is important to fully utilize the Performance Partners program, understanding how iTunes and App Store links are made will give you more flexibility in fully integrating the program into a site or an app.

There are two common types of deep links to specific items. These two types are “Clean” links, which were introduced in November of 2009, and “Legacy” WebObject links, which have been around since the inception of the store. Both types of links are supported in the store. Legacy links will continue to be supported indefinitely even though certain content is now referenced by the new Clean links.

Clean Links

Clean links are intended to give customers an indication of the content they see once they click a link. They are shorter and more user-friendly than the older style of links. A few examples of a clean link are:
http://itunes.apple.com/us/artist/blind-pilot/id284309952
http://itunes.apple.com/es/album/3-rounds-a-sound/id284309952?i=318683645
http://itunes.apple.com/fr/artist/plastic-bertrand/id78609223

Clean Links Deconstructed

Next, take a look at an example link, shown in its constituent parts. This is for U2’s “Bullet the Blue Sky” on The Joshua Tree album:
http://itunes.apple.com/us/album/joshua-tree/id267826054?i=267826366

Description Protocol Host Country Code Action Description Primary ID Query String
Example http:// itunes.apple.com /us /album /joshua-tree /id267826054 ?i=267826366
Notes [ISO-2A] Human-readable description No “=” sign Contains partner data and other information
Default Value us Optional

In some cases, the descriptive portion of the link path is removed altogether, with the id directly following the action portion. For example: http://itunes.apple.com/us/album/id267826054?i=267826366.

Country Codes and Content Availability

If you are dealing with a link that does not have a country code (for example, most EPF links are not tied to a country), you should insert one that is appropriate for your users. The country code serves as a hint to the store. If the specific content is not available in the user’s storefront, iTunes prompts the user to switch storefronts to view the requested content.

The country code also serves as a hint for the default language of the page requested when the user’s preferred language is unknown. If no country code exists on the link, iTunes defaults to the U.S. storefront.

Legacy (WebObjects) Links

These links have been around since the inception of the iTunes Store, are still supported, and will be indefinitely. The preferred host for these links is now “itunes.apple.com,” but “phobos.apple.com” links are also still supported.

Two examples of a Legacy link are:
http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewAlbum?i=315611467&id=315611219&s=143441
http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewArtist?id=954266

The Origin-Storefront Parameter

The “s,” or “origin-storefront ID,” parameter is the analog to the country code in the Clean Link format, and should be used similarly. “s,” however, must be a storefront ID (such as 143441 for the United States or 143462 for Japan). A complete listing of countries and their storefront IDs is available in the appendix to this document.

Using Partner Links Inside Apps

The use of the partners program inside apps is perfectly acceptable and in fact encouraged behavior for app developers. It is important to note that because an app is not viewed in a browser in the way a website is viewed, the behavior of a regular partner link can be somewhat jarring. There are two ways to provide a better user experience–using short links or loading the partner link in the background.

Creating Short Links

A short link is a raw link that includes the partner token parameter that is appended to the end of the link. This allows the link to still act as a partner link.

All PHG partner links are short links.

Launching Redirect in Background

A second way to keep the use of a partner link inside an app from stutter step is by loading it in the background. This is a very technical workaround and requires a high understanding of software engineering. This method is described in the Apple Developer site under the iPhone OS Reference Library – https://developer.apple.com/iphone/library/qa/qa2008/qa1629.html.

Appendix: Country Codes and Storefront IDs

Name Country Code Storefront ID
Algeria DZ 143563
Angola AO 143564
Anguilla AI 143538
Antigua & Barbuda AG 143540
Argentina AR 143505
Armenia AM 143524
Australia AU 143460
Austria AT 143445
Azerbaijan AZ 143568
Bahrain BH 143559
Bangladesh BD 143490
Barbados BB 143541
Belarus BY 143565
Belgium BE 143446
Belize BZ 143555
Bermuda BM 143542
Bolivia BO 143556
Botswana BW 143525
Brazil BR 143503
British Virgin Islands VG 143543
Brunei BN 143560
Bulgaria BG 143526
Canada CA 143455
Cayman Islands KY 143544
Chile CL 143483
China CN 143465
Colombia CO 143501
Costa Rica CR 143495
Cote D’Ivoire CI 143527
Croatia HR 143494
Cyprus CY 143557
Czech Republic CZ 143489
Denmark DK 143458
Dominica DM 143545
Dominican Rep. DO 143508
Ecuador EC 143509
Egypt EG 143516
El Salvador SV 143506
Estonia EE 143518
Finland FI 143447
France FR 143442
Germany DE 143443
Ghana GH 143573
Greece GR 143448
Grenada GD 143546
Guatemala GT 143504
Guyana GY 143553
Honduras HN 143510
Hong Kong HK 143463
Hungary HU 143482
Iceland IS 143558
India IN 143467
Indonesia ID 143476
Ireland IE 143449
Israel IL 143491
Italy IT 143450
Jamaica JM 143511
Japan JP 143462
Jordan JO 143528
Kazakstan KZ 143517
Kenya KE 143529
Korea, Republic Of KR 143466
Kuwait KW 143493
Latvia LV 143519
Lebanon LB 143497
Liechtenstein LI 143522
Lithuania LT 143520
Luxembourg LU 143451
Macau MO 143515
Macedonia MK 143530
Madagascar MG 143531
Malaysia MY 143473
Maldives MV 143488
Mali ML 143532
Malta MT 143521
Mauritius MU 143533
Mexico MX 143468
Moldova, Republic Of MD 143523
Montserrat MS 143547
Nepal NP 143484
Netherlands NL 143452
New Zealand NZ 143461
Nicaragua NI 143512
Niger NE 143534
Nigeria NG 143561
Norway NO 143457
Oman OM 143562
Pakistan PK 143477
Panama PA 143485
Paraguay PY 143513
Peru PE 143507
Philippines PH 143474
Poland PL 143478
Portugal PT 143453
Qatar QA 143498
Romania RO 143487
Russia RU 143469
Saudi Arabia SA 143479
Senegal SN 143535
Serbia RS 143500
Singapore SG 143464
Slovakia SK 143496
Slovenia SI 143499
South Africa ZA 143472
Spain ES 143454
Sri Lanka LK 143486
St. Kitts & Nevis KN 143548
St. Lucia LC 143549
St. Vincent & The Grenadines VC 143550
Suriname SR 143554
Sweden SE 143456
Switzerland CH 143459
Taiwan TW 143470
Tanzania TZ 143572
Thailand TH 143475
The Bahamas BS 143539
Trinidad & Tobago TT 143551
Tunisia TN 143536
Turkey TR 143480
Turks & Caicos TC 143552
Uganda UG 143537
UK GB 143444
Ukraine UA 143492
United Arab Emirates AE 143481
Uruguay UY 143514
USA US 143441
Uzbekistan UZ 143566
Venezuela VE 143502
Vietnam VN 143471
Yemen YE 143571

.