How often can I update my complications?

Guess I can answer my own question.

I implemented forward time travel and the method gets called with a limit of 100 events.

That will allow me to provide information for 10 minutes (10 times per minute x 10 minutes).

Once I get past 60 minutes, I can provide information for 10 hours.

So my remaining question is "Can I set the refresh for 10 minutes?"

Further information I'm discovering ...

The watch makes several calls to getTimelineEntriesForComplication to get the complications with a limit of 100 per call, so I can cover more than 10 minutes.

Here's the problem:

The watch calls getTimelineEndDateForComplication for the end date before it starts calling getTimelineEntriesForComplication.

Since I don't know how many times it's going to call getTimelineEntriesForComplication I can't accurately give the right date for getTimelineEndDateForComplication.

Fortunately, it does call getNextRequestedUpdateDateWithHandler after the last call to getTimelineEntriesForComplication, so I can simply use the last date for my entries for re-scheduling.

The problem is that my complication dims out at the time I calculated for getTimelineEndDateForComplication which is not anywhere near the time of the last entry since I don't know how many times it will call getTimelineEntriesForComplication.

To fix this, the watch should call getTimelineEndDateForComplication again after loading the timeline, or at least not dim the complication until after the last time entry.

I've seen it load between 300 and 500 entries. Each call to getTimelineEntriesForComplication uses the last entry date from the previous call. It also appears to stop after it has 24 hours of entries.

As far as I can tell from the documention and videos you need to take a look at the relative dates provider, CLKRelativeDateTextProvider basically it will allow you to establish a start time and the complication should stay updated with time, in your example in keeping with how much time you've been working on the project.

Now, depending on how you stop and start your timer for project time keeping you'll need to find the best place to invalidate the complication data in your application. The iOS app can send notifications to the watch app and change informtaion in the complicaiton using the CLKComplicationServer shared instance in conjuction with the WatchConnectivity framework.

If the user is going to open the watchapp and stop the time keeping you can use the shared CLKComplciationServer shared instance and either extend the timeline when the user selects stop or invalidate it completely and rebuild the timeline from scratch. Extending the timeline calls getCurrentTimelineEntry and and essentally pushes everything back. While invalidating the timeline will recall all the required implimented methods.

As for automatically updating I don't think that apple has actually implimented the required SDK tools for background refreshing of complications, I've been looking for information on this for a few days without success and it is only briefly mentioned but not discussed in the WWDC videos so we might have to wait a bit for that unless anyone else has any information.

Hopefully this helps!

Thanks KeatonT.

I completely missed CLKRelativeDateTextProvider in the documentation and it's exactly what I needed.

This seems like a great use case for complications. I just thought that I would point out one part of the documentation that discourages the frequent updating of complications:

The Life Cycle of a Complication

...

After gathering your data, ClockKit calls the getNextRequestedUpdateDateWithHandler: method of your data source object to determine the time for the next update cycle. Complications should provide as much data as possible during each update cycle, so specify a date as far into the future as you can manage. Do not ask the system to update your complication within minutes. Provide data to last for many hours or for an entire day.

To kinda expand on adeeb's reponse. Watching the complication WWDC session videos it seems that apple is strongly discouraging complications that update in minutes and really want developers to try hard to minimze the number of times the complication updates.

The WatchConnectivity session talked breifly about budgeting and how often you can request updates and I was shocked to hear that even if the iOS app is doing all the work in the background you'll only be able to send update requests to the complication Clock Face twice an hour, otherwise you'll exaust your budget.

I'm not entirely sure if locally scheduled wakes will allow you a larger budget but I'd imagine it would be less or it would count towards the same twice and hour update.

The sad part about that is that my app is running on the watch and doesn't need to communicate with the iPhone to update the complications. Fortunately, with the CLKRelativeDateTextProvider method, I no longer have to worry about updating the complications except when the user changes projects. That's where Apple's limit may impact my app. If someone works on several projects per hour (small tasks), they will easily exceed two updates per hour, and the complication will just keep running with the old project name.

A side observation about CLKRelativeDateTextProvider: You can't use time travel with it. If you try, it sits at whatever time is on it, and when you finish time travel, it remains locked at that time. If you don't attempt to use time travel with it, it just dims and works fine when you are done.

Giebler, if the user interacts with the watch app there is no budgeting, it is only background processes and local or remote notifications that are budgeted at what sounds like twice per hour.

So if I user changed projects in the watch app you can get the shared instance of CLKComplicationServer and extend or invalidate the timeline without any issues.