#import NS_ASSUME_NONNULL_BEGIN @class FIRInstanceIDResult; /** * @memberof FIRInstanceID * * The scope to be used when fetching/deleting a token for Firebase Messaging. */ FOUNDATION_EXPORT NSString *const kFIRInstanceIDScopeFirebaseMessaging NS_SWIFT_NAME(InstanceIDScopeFirebaseMessaging); #if defined(__IPHONE_10_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0 /** * Called when the system determines that tokens need to be refreshed. * This method is also called if Instance ID has been reset in which * case, tokens and FCM topic subscriptions also need to be refreshed. * * Instance ID service will throttle the refresh event across all devices * to control the rate of token updates on application servers. */ FOUNDATION_EXPORT const NSNotificationName kFIRInstanceIDTokenRefreshNotification NS_SWIFT_NAME(InstanceIDTokenRefresh); #else /** * Called when the system determines that tokens need to be refreshed. * This method is also called if Instance ID has been reset in which * case, tokens and FCM topic subscriptions also need to be refreshed. * * Instance ID service will throttle the refresh event across all devices * to control the rate of token updates on application servers. */ FOUNDATION_EXPORT NSString *const kFIRInstanceIDTokenRefreshNotification NS_SWIFT_NAME(InstanceIDTokenRefreshNotification); #endif // defined(__IPHONE_10_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0 /** * @related FIRInstanceID * * The completion handler invoked when the InstanceID token returns. If * the call fails we return the appropriate `error code` as described below. * * @param token The valid token as returned by InstanceID backend. * * @param error The error describing why generating a new token * failed. See the error codes below for a more detailed * description. */ typedef void (^FIRInstanceIDTokenHandler)(NSString *__nullable token, NSError *__nullable error) NS_SWIFT_NAME(InstanceIDTokenHandler); /** * @related FIRInstanceID * * The completion handler invoked when the InstanceID `deleteToken` returns. If * the call fails we return the appropriate `error code` as described below * * @param error The error describing why deleting the token failed. * See the error codes below for a more detailed description. */ typedef void (^FIRInstanceIDDeleteTokenHandler)(NSError *error) NS_SWIFT_NAME(InstanceIDDeleteTokenHandler); /** * @related FIRInstanceID * * The completion handler invoked when the app identity is created. If the * identity wasn't created for some reason we return the appropriate error code. * * @param identity A valid identity for the app instance, nil if there was an error * while creating an identity. * @param error The error if fetching the identity fails else nil. */ typedef void (^FIRInstanceIDHandler)(NSString *__nullable identity, NSError *__nullable error) NS_SWIFT_NAME(InstanceIDHandler); /** * @related FIRInstanceID * * The completion handler invoked when the app identity and all the tokens associated * with it are deleted. Returns a valid error object in case of failure else nil. * * @param error The error if deleting the identity and all the tokens associated with * it fails else nil. */ typedef void (^FIRInstanceIDDeleteHandler)(NSError *__nullable error) NS_SWIFT_NAME(InstanceIDDeleteHandler); /** * @related FIRInstanceID * * The completion handler invoked when the app identity and token are fetched. If the * identity wasn't created for some reason we return the appropriate error code. * * @param result The result containing an identity for the app instance and a valid token, * nil if there was an error while creating the result. * @param error The error if fetching the identity or token fails else nil. */ typedef void (^FIRInstanceIDResultHandler)(FIRInstanceIDResult *__nullable result, NSError *__nullable error) NS_SWIFT_NAME(InstanceIDResultHandler); /** * Public errors produced by InstanceID. */ typedef NS_ENUM(NSUInteger, FIRInstanceIDError) { // Http related errors. /// Unknown error. FIRInstanceIDErrorUnknown = 0, /// Auth Error -- GCM couldn't validate request from this client. FIRInstanceIDErrorAuthentication = 1, /// NoAccess -- InstanceID service cannot be accessed. FIRInstanceIDErrorNoAccess = 2, /// Timeout -- Request to InstanceID backend timed out. FIRInstanceIDErrorTimeout = 3, /// Network -- No network available to reach the servers. FIRInstanceIDErrorNetwork = 4, /// OperationInProgress -- Another similar operation in progress, /// bailing this one. FIRInstanceIDErrorOperationInProgress = 5, /// InvalidRequest -- Some parameters of the request were invalid. FIRInstanceIDErrorInvalidRequest = 7, } NS_SWIFT_NAME(InstanceIDError); /** * A class contains the results of InstanceID and token query. */ NS_SWIFT_NAME(InstanceIDResult) @interface FIRInstanceIDResult : NSObject /** * An instanceID uniquely identifies the app instance. */ @property(nonatomic, readonly, copy) NSString *instanceID; /* * Returns a Firebase Messaging scoped token for the firebase app. */ @property(nonatomic, readonly, copy) NSString *token; @end /** * Instance ID provides a unique identifier for each app instance and a mechanism * to authenticate and authorize actions (for example, sending an FCM message). * * Once an InstanceID is generated, the library periodically sends information about the * application and the device where it's running to the Firebase backend. To stop this. see * `[FIRInstanceID deleteIDWithHandler:]`. * * Instance ID is long lived but, may be reset if the device is not used for * a long time or the Instance ID service detects a problem. * If Instance ID is reset, the app will be notified via * `kFIRInstanceIDTokenRefreshNotification`. * * If the Instance ID has become invalid, the app can request a new one and * send it to the app server. * To prove ownership of Instance ID and to allow servers to access data or * services associated with the app, call * `[FIRInstanceID tokenWithAuthorizedEntity:scope:options:handler]`. */ NS_SWIFT_NAME(InstanceID) @interface FIRInstanceID : NSObject /** * FIRInstanceID. * * @return A shared instance of FIRInstanceID. */ + (instancetype)instanceID NS_SWIFT_NAME(instanceID()); /** * Unavailable. Use +instanceID instead. */ - (instancetype)init __attribute__((unavailable("Use +instanceID instead."))); #pragma mark - Tokens /** * Returns a result of app instance identifier InstanceID and a Firebase Messaging scoped token. * param handler The callback handler invoked when an app instanceID and a default token * are generated and returned. If instanceID and token fetching fail for some * reason the callback is invoked with nil `result` and the appropriate error. */ - (void)instanceIDWithHandler:(FIRInstanceIDResultHandler)handler; /** * Returns a Firebase Messaging scoped token for the firebase app. * * @return Returns the stored token if the device has registered with Firebase Messaging, otherwise * returns nil. */ - (nullable NSString *)token __deprecated_msg("Use instanceIDWithHandler: instead."); /** * Returns a token that authorizes an Entity (example: cloud service) to perform * an action on behalf of the application identified by Instance ID. * * This is similar to an OAuth2 token except, it applies to the * application instance instead of a user. * * This is an asynchronous call. If the token fetching fails for some reason * we invoke the completion callback with nil `token` and the appropriate * error. * * This generates an Instance ID if it does not exist yet, which starts periodically sending * information to the Firebase backend (see `[FIRInstanceID getIDWithHandler:]`). * * Note, you can only have one `token` or `deleteToken` call for a given * authorizedEntity and scope at any point of time. Making another such call with the * same authorizedEntity and scope before the last one finishes will result in an * error with code `OperationInProgress`. * * @see FIRInstanceID deleteTokenWithAuthorizedEntity:scope:handler: * * @param authorizedEntity Entity authorized by the token. * @param scope Action authorized for authorizedEntity. * @param options The extra options to be sent with your token request. The * value for the `apns_token` should be the NSData object * passed to the UIApplicationDelegate's * `didRegisterForRemoteNotificationsWithDeviceToken` method. * The value for `apns_sandbox` should be a boolean (or an * NSNumber representing a BOOL in Objective C) set to true if * your app is a debug build, which means that the APNs * device token is for the sandbox environment. It should be * set to false otherwise. If the `apns_sandbox` key is not * provided, an automatically-detected value shall be used. * @param handler The callback handler which is invoked when the token is * successfully fetched. In case of success a valid `token` and * `nil` error are returned. In case of any error the `token` * is nil and a valid `error` is returned. The valid error * codes have been documented above. */ - (void)tokenWithAuthorizedEntity:(NSString *)authorizedEntity scope:(NSString *)scope options:(nullable NSDictionary *)options handler:(FIRInstanceIDTokenHandler)handler; /** * Revokes access to a scope (action) for an entity previously * authorized by `[FIRInstanceID tokenWithAuthorizedEntity:scope:options:handler]`. * * This is an asynchronous call. Call this on the main thread since InstanceID lib * is not thread safe. In case token deletion fails for some reason we invoke the * `handler` callback passed in with the appropriate error code. * * Note, you can only have one `token` or `deleteToken` call for a given * authorizedEntity and scope at a point of time. Making another such call with the * same authorizedEntity and scope before the last one finishes will result in an error * with code `OperationInProgress`. * * @param authorizedEntity Entity that must no longer have access. * @param scope Action that entity is no longer authorized to perform. * @param handler The handler that is invoked once the unsubscribe call ends. * In case of error an appropriate error object is returned * else error is nil. */ - (void)deleteTokenWithAuthorizedEntity:(NSString *)authorizedEntity scope:(NSString *)scope handler:(FIRInstanceIDDeleteTokenHandler)handler; #pragma mark - Identity /** * Asynchronously fetch a stable identifier that uniquely identifies the app * instance. If the identifier has been revoked or has expired, this method will * return a new identifier. * * Once an InstanceID is generated, the library periodically sends information about the * application and the device where it's running to the Firebase backend. To stop this. see * `[FIRInstanceID deleteIDWithHandler:]`. * * @param handler The handler to invoke once the identifier has been fetched. * In case of error an appropriate error object is returned else * a valid identifier is returned and a valid identifier for the * application instance. */ - (void)getIDWithHandler:(FIRInstanceIDHandler)handler NS_SWIFT_NAME(getID(handler:)); /** * Resets Instance ID and revokes all tokens. * * This method also triggers a request to fetch a new Instance ID and Firebase Messaging scope * token. Please listen to kFIRInstanceIDTokenRefreshNotification when the new ID and token are * ready. * * This stops the periodic sending of data to the Firebase backend that began when the Instance ID * was generated. No more data is sent until another library calls Instance ID internally again * (like FCM, RemoteConfig or Analytics) or user explicitly calls Instance ID APIs to get an * Instance ID and token again. */ - (void)deleteIDWithHandler:(FIRInstanceIDDeleteHandler)handler NS_SWIFT_NAME(deleteID(handler:)); @end NS_ASSUME_NONNULL_END