Dispatching - iOS SDK

This document describes how you can manage dispatching data to Google Analytics using the Google Analytics SDK for iOS v3.

Overview

Data collected using the Google Analytics SDK for iOS is stored locally before being dispatched on a separate thread to Google Analytics.

Data must be dispatched and received by 4 a.m. of the following day, in the local time zone of each view. Any data received later than that will not appear in reports. For example, if a hit is queued locally at 11:59pm, it must be dispatched within 4 hours, by 3:59am, to appear in reports. On the other hand, a hit queued at 12:00am must be dispatched within 28 hours, i.e., 3:59am of the following day, in order to appear in reports.

Periodic dispatching

By default, data is dispatched from the Google Analytics SDK for iOS every 2 minutes.

// Set the dispatch interval in seconds.
// 2 minutes (120 seconds) is the default value.
[GAI sharedInstance].dispatchInterval = 120;

Setting a negative value will disable periodic dispatch, requiring that you use manual dispatch if you want to send any data to Google Analytics.

// Disable periodic dispatch by setting dispatch interval to a value less than 1.
[GAI sharedInstance].dispatchInterval = 0;

If a user loses network access or quits your app while there are still hits waiting to be dispatched, those hits are persisted in local storage. They will be dispatched the next time your app is running and dispatch is called.

Manual dispatching

To manually dispatch hits, for example when you know the device radio is already being used to send other data:

[[GAI sharedInstance] dispatch];

Background dispatching

To enable background dispatching on iOS apps:

Add a property for the dispatchHandler

In the implementation file (AppDelegate.m) of the AppDelegate class, add the following property before @implementation AppDelegate:

@interface AppDelegate ()
@property(nonatomic, copy) void (^dispatchHandler)(GAIDispatchResult result);
@end

@implementation AppDelegate
// ...

Implement the sendHitsInBackground method

In the AppDelegate class, implement the sendHitsInBackground method to send hits when the app goes into the background:

// This method sends any queued hits when the app enters the background.
- (void)sendHitsInBackground {
  __block BOOL taskExpired = NO;

  __block UIBackgroundTaskIdentifier taskId =
  [[UIApplication sharedApplication] beginBackgroundTaskWithExpirationHandler:^{
    taskExpired = YES;
  }];

  if (taskId == UIBackgroundTaskInvalid) {
    return;
  }

  __weak AppDelegate *weakSelf = self;
  self.dispatchHandler = ^(GAIDispatchResult result) {
    // Send hits until no hits are left, a dispatch error occurs, or
    // the background task expires.
    if (result == kGAIDispatchGood && !taskExpired) {
      [[GAI sharedInstance] dispatchWithCompletionHandler:weakSelf.dispatchHandler];
    } else {
      [[UIApplication sharedApplication] endBackgroundTask:taskId];
    }
  };

  [[GAI sharedInstance] dispatchWithCompletionHandler:self.dispatchHandler];
}

The method dispatchWithCompletionHandler takes a completion block as a parameter and calls that completion block each time a request containing one or more Google Analytics beacons has completed. It returns a result indicating whether there is more data to send and/or if the last request succeeded. With this method, you can manage dispatching beacons effectively when the app goes into the background.

Override the applicationDidEnterBackground method

Override the applicationDidEnterBackground method on the AppDelegate class to call the sendHitsInBackground method, which sends hits when the app goes into the background:

- (void)applicationDidEnterBackground:(UIApplication *)application {
  [self sendHitsInBackground];
}

Override the applicationWillEnterForeground method

Override the applicationWillEnterForeground method on the AppDelegate class to restore the dispatch interval. For example:

- (void)applicationWillEnterForeground:(UIApplication *)application {
  // Restores the dispatch interval because dispatchWithCompletionHandler
  // has disabled automatic dispatching.
  [GAI sharedInstance].dispatchInterval = 120;
}