321 lines
13 KiB
Objective-C
321 lines
13 KiB
Objective-C
/*
|
|
* Copyright 2019 Google
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#import <Foundation/Foundation.h>
|
|
|
|
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 <NSCopying>
|
|
|
|
/**
|
|
* 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
|