Tim Dietrich

Custom Software Developer

Home Services Portfolio Blog About Contact Newsletter

TVMLKit: Techniques for Refreshing the Index Document

When a TVMLKit-based Apple TV app starts up, the Application.js file is loaded, which presents the app's index document. From that point on, the index document will only be reloaded if the user manually closes the app or if tvOS terminates the app to free up resources. As a result, any server-side changes that you make to the index document are unlikely to be presented to the user.

I've been using a couple of techniques to force a refresh of the index document...

One technique involves configuring the AppDelegate file with either an applicationDidBecomeActive or applicationWillEnterForeground method. Depending on your app, and what you need to have happen when it resumes, this might be your best option.

Another technique is to use the App's onResume property that was introduced in tvOS 9.1. As you'd expect from its name, onResume is called every time that the app is resumed by the user. It gives us a perfect opportunity to manipulate the document stack.

Here's an example of onResume being used to force a reload of the index document.

 App.onResume = function() {   
       // Remove all documents that are on the stack.  
      navigationDocument.clear();  
      // Reload the index document, and display it by pushing it on to the stack.  
      var index = resourceLoader.loadResource(`${BASEURL}Main.php`,  
           function(resource) {  
                var doc = Presenter.makeDocument(resource);  
                doc.addEventListener("select", Presenter.load.bind(Presenter));  
                navigationDocument.pushDocument(doc);  
           }  
      );   
 }   

Here are some things to keep in mind when using this technique:

1. Users might find the constant reloading of the stack to be a little off-putting. You might want to add some code so that the index is only reloaded under certain conditions.

2. If you are going to refresh the index document, it's important to clear the document stack first. Otherwise, you'll end up with a rather strange stack, which might confuse users and eventually cause memory-related issues.

3. Be sure to take into account that the onResume function will not have access to the options that are passed to "onLaunch" function when the app initially loads. For example, it won't have access to the BASEURL option. One way to resolve this is to create global variables and set them via the onLaunch function. That's what I've done in the example above, so that onResume has access to the BASEURL value.

Another technique that I experimented with involved the use of "Cache-Control" and "Expires" headers. While this does help to prevent the caching of other documents, it does not help when it comes to the index document. The reason is that the index document has already been loaded on to the stack.

If you have any questions or comments about these techniques, or if you've found another way to refresh the index document, please feel free to drop me a line.