iOS/Pods/FirebaseInstanceID/Frameworks/FirebaseInstanceID.framework/Headers/FIRInstanceID.h

   1 #import <Foundation/Foundation.h>
   2
   3 NS_ASSUME_NONNULL_BEGIN
   4
   5 @class FIRInstanceIDResult;
   6 /**
   7  *  @memberof FIRInstanceID
   8  *
   9  *  The scope to be used when fetching/deleting a token for Firebase Messaging.
  10  */
  11 FOUNDATION_EXPORT NSString *const kFIRInstanceIDScopeFirebaseMessaging
  12     NS_SWIFT_NAME(InstanceIDScopeFirebaseMessaging);
  13
  14 #if defined(__IPHONE_10_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
  15 /**
  16  *  Called when the system determines that tokens need to be refreshed.
  17  *  This method is also called if Instance ID has been reset in which
  18  *  case, tokens and FCM topic subscriptions also need to be refreshed.
  19  *
  20  *  Instance ID service will throttle the refresh event across all devices
  21  *  to control the rate of token updates on application servers.
  22  */
  23 FOUNDATION_EXPORT const NSNotificationName kFIRInstanceIDTokenRefreshNotification
  24     NS_SWIFT_NAME(InstanceIDTokenRefresh);
  25 #else
  26 /**
  27  *  Called when the system determines that tokens need to be refreshed.
  28  *  This method is also called if Instance ID has been reset in which
  29  *  case, tokens and FCM topic subscriptions also need to be refreshed.
  30  *
  31  *  Instance ID service will throttle the refresh event across all devices
  32  *  to control the rate of token updates on application servers.
  33  */
  34 FOUNDATION_EXPORT NSString *const kFIRInstanceIDTokenRefreshNotification
  35     NS_SWIFT_NAME(InstanceIDTokenRefreshNotification);
  36 #endif  // defined(__IPHONE_10_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
  37
  38 /**
  39  *  @related FIRInstanceID
  40  *
  41  *  The completion handler invoked when the InstanceID token returns. If
  42  *  the call fails we return the appropriate `error code` as described below.
  43  *
  44  *  @param token The valid token as returned by InstanceID backend.
  45  *
  46  *  @param error The error describing why generating a new token
  47  *               failed. See the error codes below for a more detailed
  48  *               description.
  49  */
  50 typedef void (^FIRInstanceIDTokenHandler)(NSString *__nullable token, NSError *__nullable error)
  51     NS_SWIFT_NAME(InstanceIDTokenHandler);
  52
  53 /**
  54  *  @related FIRInstanceID
  55  *
  56  *  The completion handler invoked when the InstanceID `deleteToken` returns. If
  57  *  the call fails we return the appropriate `error code` as described below
  58  *
  59  *  @param error The error describing why deleting the token failed.
  60  *               See the error codes below for a more detailed description.
  61  */
  62 typedef void (^FIRInstanceIDDeleteTokenHandler)(NSError *error)
  63     NS_SWIFT_NAME(InstanceIDDeleteTokenHandler);
  64
  65 /**
  66  *  @related FIRInstanceID
  67  *
  68  *  The completion handler invoked when the app identity is created. If the
  69  *  identity wasn't created for some reason we return the appropriate error code.
  70  *
  71  *  @param identity A valid identity for the app instance, nil if there was an error
  72  *                  while creating an identity.
  73  *  @param error    The error if fetching the identity fails else nil.
  74  */
  75 typedef void (^FIRInstanceIDHandler)(NSString *__nullable identity, NSError *__nullable error)
  76     NS_SWIFT_NAME(InstanceIDHandler);
  77
  78 /**
  79  *  @related FIRInstanceID
  80  *
  81  *  The completion handler invoked when the app identity and all the tokens associated
  82  *  with it are deleted. Returns a valid error object in case of failure else nil.
  83  *
  84  *  @param error The error if deleting the identity and all the tokens associated with
  85  *               it fails else nil.
  86  */
  87 typedef void (^FIRInstanceIDDeleteHandler)(NSError *__nullable error)
  88     NS_SWIFT_NAME(InstanceIDDeleteHandler);
  89
  90 /**
  91  *  @related FIRInstanceID
  92  *
  93  *  The completion handler invoked when the app identity and token are fetched. If the
  94  *  identity wasn't created for some reason we return the appropriate error code.
  95  *
  96  *  @param result   The result containing an identity for the app instance and a valid token,
  97  *                  nil if there was an error while creating the result.
  98  *  @param error    The error if fetching the identity or token fails else nil.
  99  */
 100 typedef void (^FIRInstanceIDResultHandler)(FIRInstanceIDResult *__nullable result,
 101                                            NSError *__nullable error)
 102     NS_SWIFT_NAME(InstanceIDResultHandler);
 103
 104 /**
 105  * Public errors produced by InstanceID.
 106  */
 107 typedef NS_ENUM(NSUInteger, FIRInstanceIDError) {
 108   // Http related errors.
 109
 110   /// Unknown error.
 111   FIRInstanceIDErrorUnknown = 0,
 112
 113   /// Auth Error -- GCM couldn't validate request from this client.
 114   FIRInstanceIDErrorAuthentication = 1,
 115
 116   /// NoAccess -- InstanceID service cannot be accessed.
 117   FIRInstanceIDErrorNoAccess = 2,
 118
 119   /// Timeout -- Request to InstanceID backend timed out.
 120   FIRInstanceIDErrorTimeout = 3,
 121
 122   /// Network -- No network available to reach the servers.
 123   FIRInstanceIDErrorNetwork = 4,
 124
 125   /// OperationInProgress -- Another similar operation in progress,
 126   /// bailing this one.
 127   FIRInstanceIDErrorOperationInProgress = 5,
 128
 129   /// InvalidRequest -- Some parameters of the request were invalid.
 130   FIRInstanceIDErrorInvalidRequest = 7,
 131 } NS_SWIFT_NAME(InstanceIDError);
 132
 133 /**
 134  * A class contains the results of InstanceID and token query.
 135  */
 136 NS_SWIFT_NAME(InstanceIDResult)
 137 @interface FIRInstanceIDResult : NSObject <NSCopying>
 138
 139 /**
 140  * An instanceID uniquely identifies the app instance.
 141  */
 142 @property(nonatomic, readonly, copy) NSString *instanceID;
 143
 144 /*
 145  * Returns a Firebase Messaging scoped token for the firebase app.
 146  */
 147 @property(nonatomic, readonly, copy) NSString *token;
 148
 149 @end
 150
 151 /**
 152  *  Instance ID provides a unique identifier for each app instance and a mechanism
 153  *  to authenticate and authorize actions (for example, sending an FCM message).
 154  *
 155  *  Once an InstanceID is generated, the library periodically sends information about the
 156  *  application and the device where it's running to the Firebase backend. To stop this. see
 157  *  `[FIRInstanceID deleteIDWithHandler:]`.
 158  *
 159  *  Instance ID is long lived but, may be reset if the device is not used for
 160  *  a long time or the Instance ID service detects a problem.
 161  *  If Instance ID is reset, the app will be notified via
 162  *  `kFIRInstanceIDTokenRefreshNotification`.
 163  *
 164  *  If the Instance ID has become invalid, the app can request a new one and
 165  *  send it to the app server.
 166  *  To prove ownership of Instance ID and to allow servers to access data or
 167  *  services associated with the app, call
 168  *  `[FIRInstanceID tokenWithAuthorizedEntity:scope:options:handler]`.
 169  */
 170 NS_SWIFT_NAME(InstanceID)
 171 @interface FIRInstanceID : NSObject
 172
 173 /**
 174  *  FIRInstanceID.
 175  *
 176  *  @return A shared instance of FIRInstanceID.
 177  */
 178 + (instancetype)instanceID NS_SWIFT_NAME(instanceID());
 179
 180 /**
 181  *  Unavailable. Use +instanceID instead.
 182  */
 183 - (instancetype)init __attribute__((unavailable("Use +instanceID instead.")));
 184
 185 #pragma mark - Tokens
 186
 187 /**
 188  * Returns a result of app instance identifier InstanceID and a Firebase Messaging scoped token.
 189  * param handler    The callback handler invoked when an app instanceID and a default token
 190  *                  are generated and returned. If instanceID and token fetching fail for some
 191  *                  reason the callback is invoked with nil `result` and the appropriate error.
 192  */
 193 - (void)instanceIDWithHandler:(FIRInstanceIDResultHandler)handler;
 194
 195 /**
 196  *  Returns a Firebase Messaging scoped token for the firebase app.
 197  *
 198  *  @return Returns the stored token if the device has registered with Firebase Messaging, otherwise
 199  *          returns nil.
 200  */
 201 - (nullable NSString *)token __deprecated_msg("Use instanceIDWithHandler: instead.");
 202
 203 /**
 204  *  Returns a token that authorizes an Entity (example: cloud service) to perform
 205  *  an action on behalf of the application identified by Instance ID.
 206  *
 207  *  This is similar to an OAuth2 token except, it applies to the
 208  *  application instance instead of a user.
 209  *
 210  *  This is an asynchronous call. If the token fetching fails for some reason
 211  *  we invoke the completion callback with nil `token` and the appropriate
 212  *  error.
 213  *
 214  *  This generates an Instance ID if it does not exist yet, which starts periodically sending
 215  *  information to the Firebase backend (see `[FIRInstanceID getIDWithHandler:]`).
 216  *
 217  *  Note, you can only have one `token` or `deleteToken` call for a given
 218  *  authorizedEntity and scope at any point of time. Making another such call with the
 219  *  same authorizedEntity and scope before the last one finishes will result in an
 220  *  error with code `OperationInProgress`.
 221  *
 222  *  @see FIRInstanceID deleteTokenWithAuthorizedEntity:scope:handler:
 223  *
 224  *  @param authorizedEntity Entity authorized by the token.
 225  *  @param scope            Action authorized for authorizedEntity.
 226  *  @param options          The extra options to be sent with your token request. The
 227  *                          value for the `apns_token` should be the NSData object
 228  *                          passed to the UIApplicationDelegate's
 229  *                          `didRegisterForRemoteNotificationsWithDeviceToken` method.
 230  *                          The value for `apns_sandbox` should be a boolean (or an
 231  *                          NSNumber representing a BOOL in Objective C) set to true if
 232  *                          your app is a debug build, which means that the APNs
 233  *                          device token is for the sandbox environment. It should be
 234  *                          set to false otherwise. If the `apns_sandbox` key is not
 235  *                          provided, an automatically-detected value shall be used.
 236  *  @param handler          The callback handler which is invoked when the token is
 237  *                          successfully fetched. In case of success a valid `token` and
 238  *                          `nil` error are returned. In case of any error the `token`
 239  *                          is nil and a valid `error` is returned. The valid error
 240  *                          codes have been documented above.
 241  */
 242 - (void)tokenWithAuthorizedEntity:(NSString *)authorizedEntity
 243                             scope:(NSString *)scope
 244                           options:(nullable NSDictionary *)options
 245                           handler:(FIRInstanceIDTokenHandler)handler;
 246
 247 /**
 248  *  Revokes access to a scope (action) for an entity previously
 249  *  authorized by `[FIRInstanceID tokenWithAuthorizedEntity:scope:options:handler]`.
 250  *
 251  *  This is an asynchronous call. Call this on the main thread since InstanceID lib
 252  *  is not thread safe. In case token deletion fails for some reason we invoke the
 253  *  `handler` callback passed in with the appropriate error code.
 254  *
 255  *  Note, you can only have one `token` or `deleteToken` call for a given
 256  *  authorizedEntity and scope at a point of time. Making another such call with the
 257  *  same authorizedEntity and scope before the last one finishes will result in an error
 258  *  with code `OperationInProgress`.
 259  *
 260  *  @param authorizedEntity Entity that must no longer have access.
 261  *  @param scope            Action that entity is no longer authorized to perform.
 262  *  @param handler          The handler that is invoked once the unsubscribe call ends.
 263  *                          In case of error an appropriate error object is returned
 264  *                          else error is nil.
 265  */
 266 - (void)deleteTokenWithAuthorizedEntity:(NSString *)authorizedEntity
 267                                   scope:(NSString *)scope
 268                                 handler:(FIRInstanceIDDeleteTokenHandler)handler;
 269
 270 #pragma mark - Identity
 271
 272 /**
 273  *  Asynchronously fetch a stable identifier that uniquely identifies the app
 274  *  instance. If the identifier has been revoked or has expired, this method will
 275  *  return a new identifier.
 276  *
 277  *  Once an InstanceID is generated, the library periodically sends information about the
 278  *  application and the device where it's running to the Firebase backend. To stop this. see
 279  *  `[FIRInstanceID deleteIDWithHandler:]`.
 280  *
 281  *  @param handler The handler to invoke once the identifier has been fetched.
 282  *                 In case of error an appropriate error object is returned else
 283  *                 a valid identifier is returned and a valid identifier for the
 284  *                 application instance.
 285  */
 286 - (void)getIDWithHandler:(FIRInstanceIDHandler)handler NS_SWIFT_NAME(getID(handler:));
 287
 288 /**
 289  *  Resets Instance ID and revokes all tokens.
 290  *
 291  *  This method also triggers a request to fetch a new Instance ID and Firebase Messaging scope
 292  *  token. Please listen to kFIRInstanceIDTokenRefreshNotification when the new ID and token are
 293  *  ready.
 294  *
 295  *  This stops the periodic sending of data to the Firebase backend that began when the Instance ID
 296  *  was generated. No more data is sent until another library calls Instance ID internally again
 297  *  (like FCM, RemoteConfig or Analytics) or user explicitly calls Instance ID APIs to get an
 298  *  Instance ID and token again.
 299  */
 300 - (void)deleteIDWithHandler:(FIRInstanceIDDeleteHandler)handler NS_SWIFT_NAME(deleteID(handler:));
 301
 302 @end
 303
 304 NS_ASSUME_NONNULL_END