Changing URLs or Text using a Macro

• This Instant TV Channel walk-through applies only to Custom SDK Roku channels. Macros are not currently supported in Direct Publisher Roku channels.

Occassionally it is necessary to change many parameters 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

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 PosterUrl or ListPosterUrl, but not text parameters like Title or Description. If you want to change text parameters instead of URL parameters, change the ControlType to "text macro" instead.
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 be replaced, you can use the pipe symbol "|" within the macro instruction in place of the colon. For example, here's an example macro instruction to replace "http://red.com" with "https://green.com":

       http://red.com|https://green.com

• 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 letters, with "Dog":

       cat:Dog
       CAT:Dog

• The ControlTypes "url purchase macro" and "text purchase macro" work the same way as "url macro" and "text macro", except they are conditional on a Product ID having been purchased or not. The Product ID is placed at the beginning of the macro instruction, followed by a colon ":", the sequence of characters to be replaced, another colon ":", and finally the sequence of replacement characters. For example, here's an example macro instruction to replace "cat" with "dog" if the Product ID "mypid" has been purchased:

       mypid:cat:dog

• Placing an exclamation point "!" in front of a Product ID negates the operation of a "purchase macro", so that the substitution is performed if the Product ID has not been purchased. For example, here's an example macro instruction to replace "cat" with "dog" if the Product ID "mypid" has not been purchased:

       !mypid: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 .