Changing URLs or Text using a Control Item

Occassionally it is necessary to change many parameters in your Roku app at the same time. For example, if you move the files for your app's posters to a different S3 bucket or to a different web server, then every URL in your Roku app 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 Control Item will be. The instructions tell the Control Item what sequence of characters in the URLs to look for, and what to replace them with. The technical term for the instructions is a macro. 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 would look like this:

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

The macro consists of a sequence of characters to search for, followed by a colon ":", followed by a sequence of replacement characters.

When your Roku app is started on a viewer's Roku device, the example macro 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 to a Roku app:

1. Add a new Control item to the app'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". This is for your convenience only, and does not affect the operation of the Control item.
3. Change the ControlType to "url macro". This tells the Control item 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 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 app 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 in place of the colon. For example, here's an example macro 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, 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 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 to replace "cat" with "dog" if the Product ID "mypid" has not been purchased:

       !mypid:cat:dog

• Control items can only be located at the top of the content tree.

---

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

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