I thought I was going to need help figuring this out — turns out I’ve got more iTMS link-fu than I thought. :D
Earlier this month, I was accepted into the iTunes Affiliate program. All well and good, except that at that point, I couldn’t find a way to link directly to individual items with my Affiliate ID — I could put up the generic iTunes badge (which now resides towards the bottom of my sidebar), or I could put up Apple-designed ad blocks (which, aside from the Björk ad on my original post, I’ve yet to do, mostly because they apparently need to be rotated out manually), but I couldn’t link to any particular track.
As of today, however, Apple now provides a tool to let me do just that, in the form of an addition to the iTMS Link Maker. This is most definitely a Good Thing — however, it’s still a lot more cumbersome than I’d like things to be. While it will be serviceable when I want to mention a particular track or album during the course of a post (for instance, right now I’m listening to William S. Burroughs’ spoken word album Dead City Radio, a must for any WSB fan), what I really wanted to be able to do is use ecto‘s ‘now playing’ feature (which I use to insert the currently playing iTunes track information into the bottom of posts I make at home) to autogenerate iTMS search links that include my Affiliate information at the beginning.
Back when the iTMS first debuted, some enterprising people figured out the URL structure that would allow you to create links to iTMS searches — in theory, all I should have to do is slightly adjust that URL structure to match the URL structure of Affiliate links, and I’d be good to go. As it turns out, that theory was right — for instance, here’s an iTMS search for U2 that passes through my Affiliate information.
Full gory details are in the extended entry…
(NOTE: There are a lot of really long URLs in the following post. For the sake of readability, I’ve broken them down with spaces in this text — should you do any copy-and-pasting of any of the code I’ve posted here, please keep in mind that all the URLs should be one single line.)
Here’s what I had to do to get this working:
When I got the announcement in the e-mail from Apple, they included a link to the iTMS Link Maker. However, when I clicked through to give it a shot, the returned URL was a generic URL that didn’t include the data that LinkSynergy needs to connect the click-through with my Affiliate account:
http://click.linksynergy.com/fs-bin/stat?id=[SITE.CODE]&offerid=
[OFFER.OID]&type=3&subid=0&tmpid=1826&RD_PARM1=http%253A%252F%252F
phobos.apple.com%252FWebObjects%252FMZStore.woa%252Fwa%252FviewArtist
%253FartistId%253D78500%2526originStoreFront%253D143441%26 partnerId%3D30
See those [SITE.CODE] and [OFFER.OID] arguments? Without actual data in those, the link doesn’t work. Not an auspicious start to my project.
Wondering if there might be a way to get to the iTMS Link Maker through my LinkSynergy account and then generate links that included my site code and offer oid (would that be any relation to the Noid?), I headed over to my LinkShare account page. Sure enough, today’s announcement was mirrored there, and when I clicked through to the iTMS Link Maker and performed the same search, I was returned a full-formed, working URL:
http://click.linksynergy.com/fs-bin/stat?id=xLsJkztrnNY&offerid=
78941&type=3&subid=0&tmpid=1826&RD_PARM1=http%253A%252F%252Fphobos.
apple.com%252FWebObjects%252FMZStore.woa%252Fwa%252FviewArtist
%253FartistId%253D78500%2526originStoreFront%253D143441%26 partnerId%3D30
Much better! Just to be sure, I performed a few searches to be sure that neither of the variables changed — neither did, so I’m pretty certain that those are constants.
Immediately, I went back to the iTMS Link Maker through the link from within my LinkShare page and bookmarked that page, then performed a few searches using the bookmark to ensure that they’d give me consistent, well-formed URLs to play with. They did — so on to the next step.
Looking at the URL, it seemed fairly obvious that it had two parts: the URL that actually gets passed to the iTunes Music Store, and the LinkShare information that ties the click-through to my Affiliate account. In order to break it apart, I opened the iTunes Link Maker in two tabs — once ‘anonymously’, and once tied to my Affiliate account — and performed the same search twice so that I could compare the information returned by the searches.
- Anonymous link:
http://phobos.apple.com/WebObjects/MZStore.woa/
wa/viewArtist?artistId=78500&originStoreFront=143441 -
Affiliate link:
http://click.linksynergy.com/fs-bin/stat?
id=xLsJkztrnNY&offerid=78941&type=3&subid=0&tmpid=1826&
RD_PARM1=http%253A%252F%252Fphobos.apple.com%252FWebObjects
%252FMZStore.woa%252Fwa%252FviewArtist%253FartistId%253D
78500%2526originStoreFront%253D143441%26partnerId%3D30
While the Affiliate link looks a lot nastier, it turns out that it’s exactly what I thought it would be, only all non-alphanumeric characters (except periods, for some reason) in the iTMS link have been encoded into their ASCII entities. The following is the Affiliate link with the LinkShare information in red, and the iTMS information in green:
http://click.linksynergy.com/fs-bin/stat?
id=xLsJkztrnNY&offerid=78941&type=3&subid=0&tmpid=1826&RD_PARM1=
http%253A%252F%252Fphobos.apple.com%252FWebObjects%252FMZStore.woa
%252Fwa%252FviewArtist%253FartistId%253D78500%2526originStoreFront
%253D143441%26partnerId%3D30
I’m pretty sure that that last red bit at the end actually does get passed to the iTMS, but as it’s not there with a ‘normal’ (anonymous) link, I’m including it as LinkShare-specific information.
So, now I knew that in order to create my search links, I’d need to surround an iTMS search URL with the LinkShare specific code, and encode the non-alphanumeric characters within the iTMS search URL. According to the information I had on constructing iTMS search URLs, the iTMS search string for ‘U2’ would be…
itms://phobos.apple.com/WebObjects/MZSearch.woa/wa/com.apple.jingle.search.
DirectAction/advancedSearchResults?artistTerm=U2
…so with a little careful comparison to be sure I was substituting the right ASCII entities for the right characters, I ended up with an encoded search URL of…
http%253A%252F%252Fphobos.apple.com%252FWebObjects%252FMZSearch.woa%252Fwa
%252Fcom.apple.jingle.search.DirectAction%252FadvancedSearchResults%253F
artistTerm%253DU2
…(note that the iTMS Search URL now begins with
http, and not
itms). Surrounding that with the LinkShare code gave me a final URL of…
…and what do you know, but the fool thing worked!
Now I had the correct syntax and URL structure to be able to create Affiliate-linked searches within the iTMS for any artist that I wanted. The final step is to craft the correct ecto iTunes template for automatic generation of search strings at the end of each post. Rather than run through every step of that process, I’ll just post the final string that works for me (I have it as a single long string, I’m breaking it down here for [marginally] better readability):
<a href="http://click.linksynergy.com/fs-bin/click?id=xLsJkztrnNY&
offerid=78941.10000170&type=4&subid=0" title="Get iTunes"><img alt="iTunes" border="0" width="61" height="15" src="http://images.apple.
com/itunesaffiliates/logos/iTunes_sm_bdg61x15.png" /></a><img border="0" width="1" height="1" src="http://ad.linksynergy.com/fs-bin/show?id=
xLsJkztrnNY&bids=78941.10000170&type=4&subid=0" alt="" />
"<a href="http://click.linksynergy.com/fs-bin/stat?id=xLsJkztrnNY&
offerid=78941&type=3&subid=0&tmpid=1826&RD_PARM1=itms
%253A%252F%252Fphobos.apple.com%252FWebObjects%252FMZSearch.woa%252Fwa
%252Fcom.apple.jingle.search.DirectAction%252FadvancedSearchResults%253F
artistTerm%253D^p%2526songTerm=^t%26partnerId%3D30" title="Search for '^t'
on the iTMS">^t</a>"#p by <a href="http://click.linksynergy.com/fs-bin/
stat?id=xLsJkztrnNY&offerid=78941&type=3&subid=0&tmpid=
1826&RD_PARM1=itms%253A%252F%252Fphobos.apple.com%252FWebObjects%252F
MZSearch.woa%252Fwa%252Fcom.apple.jingle.search.DirectAction%252Fadvanced
SearchResults%253FartistTerm%253D^p%26partnerId%3D30" title="Search for
'^p' on the iTMS">^p</a>#p#a from the album <em><a href="http://click.
linksynergy.com/fs-bin/stat?id=xLsJkztrnNY&offerid=78941&type=
3&subid=0&tmpid=1826&RD_PARM1=itms%253A%252F%252Fphobos.apple.
com%252FWebObjects%252FMZSearch.woa%252Fwa%252Fcom.apple.jingle.search.
DirectAction%252FadvancedSearchResults%253FartistTerm%253D^p%2526
albumTerm=^a%26partnerId%3D30" title="Search for '^a' on the iTMS">^a</a>
</em>#a (#y^y, #y^l).
Update: The above code has been slightly tweaked (mostly just adding title attributes to the links) during a debugging session to ensure that it was still working as it should. As far as I can tell, it’s still working fine.
Update:: Another minor tweak to adjust for Apple’s change of location and filename for the small iTunes badge image.
While you can see the results of this (admittedly huge) code block at the end of this post, it does the following:
- Wraps the iTunes information in a CSS class that I’ve specified for positioning, font, etc.
- Creates an iTunes badge that links to the iTMS
- Links the title of the currently playing track to an iTMS search for the title, artist, and album
- Links the artist to an iTMS search for the artist
- Links the album to an iTMS search for the artist and album
- All of the links are tied to my iTunes Affiliate ID
And so, in the end, I’ve got exactly what I wanted when I first heard about the iTMS Affiliate program: dynamic iTMS searches for anything I’m listening to when I make a post. The one downside, of course, is that I listen to enough obscure music that there will be times when none of those searches return any useable results…but that’s just one of the many potential side effects of being a music whore, so I think I can live with that. ;)
Hopefully if you’ve been able to make it through all this, my somewhat stream-of-conscious ramblings will have been of some assistance (especially if you’re an iTunes Affiliate who’d like to do the same thing, or something similar). Let me know if I can clear anything up (I’ll probably want to come back and create a condensed, ‘here’s the basics’ rundown of how to do this…but at the moment, constructing this post has taken twice as long as the actual detective work did, I still need to proofread it before posting, and that’ll be about all I’m up for at the moment).
“Heartland” by U2 from the album Rattle and Hum (1988, 5:03).