Changing URLs using a Macro


• This Instant TV Channel walk-through applies only to Developer SDK Roku channels. Macros are not currently supported in Direct Publisher Roku channels.
• Your channel must either be newly created, or be at Update #311 or higher in order to use URL Macros.

Occassionally it is necessary to change many URLs in your Roku channel at the same time. For example, if you move the files for your channel's posters to a different S3 bucket or to a different web server, then every URL in your Roku channel will need to be changed. Fortunately there is a very quick and easy way to do this!

Before starting, you'll need to determine what the instructions for the macro will be. The instructions tell the macro what sequence of characters in the URLs to look for, and what to replace them with. For example, if your current poster URLs look something like this:

     http://www.posterhosting.com/mydirectory/poster1.jpg

And your new poster URLs need to look like this:

     http://www.newposters.com/other/directory/poster1.jpg

Then the macro instructions would look like this:

     posterhosting.com/mydirectory:newposters.com/other/directory

Basically, the instruction consists of a sequence of characters to search for, followed by a colon ":", followed by a sequence of replacement characters.

When your Roku channel is started on a viewer's Roku device, the example macro instruction above will find all instances of "posterhosting.com/mydirectory" and replace them with "newposters.com/other/directory".

Here are the steps you would take to add the example macro instruction to a Roku channel:

  1. Add a new Control item to the channel's content tree by right-clicking on the top-level yellow folder and selecting "New Control".
  2. Change the title of the Control item to something that indicates what it will do, like "My URL Fixup".
  3. Change the ControlType to "url macro". This tells the macro that it should only check & modify URL parameters like HDPosterUrl or SDListPosterUrl, but not text parameters like Title or Description.
  4. Enter the instructions for the macro into the ControlParagraph box:

         posterhosting.com/mydirectory:newposters.com/other/directory

  5. That's it, you're done. There will not be any visible change to the URLs within the Instant TV Channel Content page, but the URLs will be changed within the viewer's Roku device every time the channel is started.

Here are some other important things to know about macros:

  • If you want to use the colon ":" as part of the text to substituted, you'll need replace the colon with special sequence %3A within the macro instruction. For example, here's an example macro instruction to replace "http://red" with "https://green":

         http%3A//red:https%3A//green

  • The comparison to determine if a macro susbstitution should be performed is case insensitive. For example these 2 macro instructions are the same, both will replace "Cat", in any combination of upper and lower case letter, with "Dog":

         cat:Dog
         CAT:Dog

  • The position of the Control item in the Content Tree is important. You will usually want to put the Control item at the top of the Content Tree, otherwise substitutions that do not take place on the Springboard/Detail screens may not occur.


Need help with monetizing your Roku channel using video advertisements? See Placing Advertisements in your Roku Channel for all the details!

Comments, suggestions, or questions about this Roku developer guide can be sent to .

Instant TV Channel is a cloud-based tool for Roku developers and content providers that shortens development time and eases maintenance after deployment.



Access Code: GRID3
Check out Instant TV Channel by adding our demonstration channel to your Roku player, or watch the YouTube video.

Need help with your Roku?

We are unable to provide technical support for your Roku device.

Please visit www.roku.com for assistance.



Instant TV Channel is not affiliated with nor endorsed by Roku Inc.