status-mobile/ios/FirebaseMessaging.framework/Headers/FIRMessaging.h

493 lines
20 KiB
Objective-C
Executable File
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/*
* Copyright 2017 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_SWIFT_NAME can only translate factory methods before the iOS 9.3 SDK.
// Wrap it in our own macro if it's a non-compatible SDK.
#ifndef FIR_SWIFT_NAME
#ifdef __IPHONE_9_3
#define FIR_SWIFT_NAME(X) NS_SWIFT_NAME(X)
#else
#define FIR_SWIFT_NAME(X) // Intentionally blank.
#endif // #ifdef __IPHONE_9_3
#endif // #ifndef FIR_SWIFT_NAME
/**
* @related FIRMessaging
*
* The completion handler invoked when the registration token returns.
* If the call fails we return the appropriate `error code`, described by
* `FIRMessagingError`.
*
* @param FCMToken The valid registration token returned by FCM.
* @param error The error describing why a token request failed. The error code
* will match a value from the FIRMessagingError enumeration.
*/
typedef void(^FIRMessagingFCMTokenFetchCompletion)(NSString * _Nullable FCMToken,
NSError * _Nullable error)
FIR_SWIFT_NAME(MessagingFCMTokenFetchCompletion);
/**
* @related FIRMessaging
*
* The completion handler invoked when the registration token deletion request is
* completed. If the call fails we return the appropriate `error code`, described
* by `FIRMessagingError`.
*
* @param error The error describing why a token deletion failed. The error code
* will match a value from the FIRMessagingError enumeration.
*/
typedef void(^FIRMessagingDeleteFCMTokenCompletion)(NSError * _Nullable error)
FIR_SWIFT_NAME(MessagingDeleteFCMTokenCompletion);
/**
* The completion handler invoked once the data connection with FIRMessaging is
* established. The data connection is used to send a continous stream of
* data and all the FIRMessaging data notifications arrive through this connection.
* Once the connection is established we invoke the callback with `nil` error.
* Correspondingly if we get an error while trying to establish a connection
* we invoke the handler with an appropriate error object and do an
* exponential backoff to try and connect again unless successful.
*
* @param error The error object if any describing why the data connection
* to FIRMessaging failed.
*/
typedef void(^FIRMessagingConnectCompletion)(NSError * __nullable error)
FIR_SWIFT_NAME(MessagingConnectCompletion)
__deprecated_msg("Please listen for the FIRMessagingConnectionStateChangedNotification "
"NSNotification instead.");
#if defined(__IPHONE_10_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
/**
* Notification sent when the upstream message has been delivered
* successfully to the server. The notification object will be the messageID
* of the successfully delivered message.
*/
FOUNDATION_EXPORT const NSNotificationName __nonnull FIRMessagingSendSuccessNotification
FIR_SWIFT_NAME(MessagingSendSuccess);
/**
* Notification sent when the upstream message was failed to be sent to the
* server. The notification object will be the messageID of the failed
* message. The userInfo dictionary will contain the relevant error
* information for the failure.
*/
FOUNDATION_EXPORT const NSNotificationName __nonnull FIRMessagingSendErrorNotification
FIR_SWIFT_NAME(MessagingSendError);
/**
* Notification sent when the Firebase messaging server deletes pending
* messages due to exceeded storage limits. This may occur, for example, when
* the device cannot be reached for an extended period of time.
*
* It is recommended to retrieve any missing messages directly from the
* server.
*/
FOUNDATION_EXPORT const NSNotificationName __nonnull FIRMessagingMessagesDeletedNotification
FIR_SWIFT_NAME(MessagingMessagesDeleted);
/**
* Notification sent when Firebase Messaging establishes or disconnects from
* an FCM socket connection. You can query the connection state in this
* notification by checking the `isDirectChannelEstablished` property of FIRMessaging.
*/
FOUNDATION_EXPORT const NSNotificationName __nonnull FIRMessagingConnectionStateChangedNotification
FIR_SWIFT_NAME(MessagingConnectionStateChanged);
/**
* Notification sent when the FCM registration token has been refreshed. You can also
* receive the FCM token via the FIRMessagingDelegate method
* `-messaging:didRefreshRegistrationToken:`
*/
FOUNDATION_EXPORT const NSNotificationName __nonnull
FIRMessagingRegistrationTokenRefreshedNotification
FIR_SWIFT_NAME(MessagingRegistrationTokenRefreshed);
#else
/**
* Notification sent when the upstream message has been delivered
* successfully to the server. The notification object will be the messageID
* of the successfully delivered message.
*/
FOUNDATION_EXPORT NSString * __nonnull const FIRMessagingSendSuccessNotification
FIR_SWIFT_NAME(MessagingSendSuccessNotification);
/**
* Notification sent when the upstream message was failed to be sent to the
* server. The notification object will be the messageID of the failed
* message. The userInfo dictionary will contain the relevant error
* information for the failure.
*/
FOUNDATION_EXPORT NSString * __nonnull const FIRMessagingSendErrorNotification
FIR_SWIFT_NAME(MessagingSendErrorNotification);
/**
* Notification sent when the Firebase messaging server deletes pending
* messages due to exceeded storage limits. This may occur, for example, when
* the device cannot be reached for an extended period of time.
*
* It is recommended to retrieve any missing messages directly from the
* server.
*/
FOUNDATION_EXPORT NSString * __nonnull const FIRMessagingMessagesDeletedNotification
FIR_SWIFT_NAME(MessagingMessagesDeletedNotification);
/**
* Notification sent when Firebase Messaging establishes or disconnects from
* an FCM socket connection. You can query the connection state in this
* notification by checking the `isDirectChannelEstablished` property of FIRMessaging.
*/
FOUNDATION_EXPORT NSString * __nonnull const FIRMessagingConnectionStateChangedNotification
FIR_SWIFT_NAME(MessagingConnectionStateChangedNotification);
/**
* Notification sent when the FCM registration token has been refreshed. You can also
* receive the FCM token via the FIRMessagingDelegate method
* `-messaging:didRefreshRegistrationToken:`
*/
FOUNDATION_EXPORT NSString * __nonnull const FIRMessagingRegistrationTokenRefreshedNotification
FIR_SWIFT_NAME(MessagingRegistrationTokenRefreshedNotification);
#endif // defined(__IPHONE_10_0) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_10_0
/**
* @enum FIRMessagingError
*/
typedef NS_ENUM(NSUInteger, FIRMessagingError) {
/// Unknown error.
FIRMessagingErrorUnknown = 0,
/// FIRMessaging couldn't validate request from this client.
FIRMessagingErrorAuthentication = 1,
/// InstanceID service cannot be accessed.
FIRMessagingErrorNoAccess = 2,
/// Request to InstanceID backend timed out.
FIRMessagingErrorTimeout = 3,
/// No network available to reach the servers.
FIRMessagingErrorNetwork = 4,
/// Another similar operation in progress, bailing this one.
FIRMessagingErrorOperationInProgress = 5,
/// Some parameters of the request were invalid.
FIRMessagingErrorInvalidRequest = 7,
} FIR_SWIFT_NAME(MessagingError);
/// Status for the downstream message received by the app.
typedef NS_ENUM(NSInteger, FIRMessagingMessageStatus) {
/// Unknown status.
FIRMessagingMessageStatusUnknown,
/// New downstream message received by the app.
FIRMessagingMessageStatusNew,
} FIR_SWIFT_NAME(MessagingMessageStatus);
/**
* The APNS token type for the app. If the token type is set to `UNKNOWN`
* Firebase Messaging will implicitly try to figure out what the actual token type
* is from the provisioning profile.
* Unless you really need to specify the type, you should use the `APNSToken`
* property instead.
*/
typedef NS_ENUM(NSInteger, FIRMessagingAPNSTokenType) {
/// Unknown token type.
FIRMessagingAPNSTokenTypeUnknown,
/// Sandbox token type.
FIRMessagingAPNSTokenTypeSandbox,
/// Production token type.
FIRMessagingAPNSTokenTypeProd,
} FIR_SWIFT_NAME(MessagingAPNSTokenType);
/// Information about a downstream message received by the app.
FIR_SWIFT_NAME(MessagingMessageInfo)
@interface FIRMessagingMessageInfo : NSObject
/// The status of the downstream message
@property(nonatomic, readonly, assign) FIRMessagingMessageStatus status;
@end
/**
* A remote data message received by the app via FCM (not just the APNs interface).
*
* This is only for devices running iOS 10 or above. To support devices running iOS 9 or below, use
* the local and remote notifications handlers defined in UIApplicationDelegate protocol.
*/
FIR_SWIFT_NAME(MessagingRemoteMessage)
@interface FIRMessagingRemoteMessage : NSObject
/// The downstream message received by the application.
@property(nonatomic, readonly, strong, nonnull) NSDictionary *appData;
@end
@class FIRMessaging;
/**
* A protocol to handle events from FCM for devices running iOS 10 or above.
*
* To support devices running iOS 9 or below, use the local and remote notifications handlers
* defined in UIApplicationDelegate protocol.
*/
FIR_SWIFT_NAME(MessagingDelegate)
@protocol FIRMessagingDelegate <NSObject>
/// This method will be called whenever FCM receives a new, default FCM token for your
/// Firebase project's Sender ID.
/// You can send this token to your application server to send notifications to this device.
- (void)messaging:(nonnull FIRMessaging *)messaging
didRefreshRegistrationToken:(nonnull NSString *)fcmToken
FIR_SWIFT_NAME(messaging(_:didRefreshRegistrationToken:));
@optional
/// This method is called on iOS 10 devices to handle data messages received via FCM through its
/// direct channel (not via APNS). For iOS 9 and below, the FCM data message is delivered via the
/// UIApplicationDelegate's -application:didReceiveRemoteNotification: method.
- (void)messaging:(nonnull FIRMessaging *)messaging
didReceiveMessage:(nonnull FIRMessagingRemoteMessage *)remoteMessage
FIR_SWIFT_NAME(messaging(_:didReceive:))
__IOS_AVAILABLE(10.0);
/// The callback to handle data message received via FCM for devices running iOS 10 or above.
- (void)applicationReceivedRemoteMessage:(nonnull FIRMessagingRemoteMessage *)remoteMessage
FIR_SWIFT_NAME(application(received:))
__deprecated_msg("Use FIRMessagingDelegates -messaging:didReceiveMessage:");
@end
/**
* Firebase Messaging lets you reliably deliver messages at no cost.
*
* To send or receive messages, the app must get a
* registration token from FIRInstanceID. This token authorizes an
* app server to send messages to an app instance.
*
* In order to receive FIRMessaging messages, declare `application:didReceiveRemoteNotification:`.
*/
FIR_SWIFT_NAME(Messaging)
@interface FIRMessaging : NSObject
/**
* Delegate to handle FCM token refreshes, and remote data messages received via FCM for devices
* running iOS 10 or above.
*/
@property(nonatomic, weak, nullable) id<FIRMessagingDelegate> delegate;
/**
* Delegate to handle remote data messages received via FCM for devices running iOS 10 or above.
*/
@property(nonatomic, weak, nullable) id<FIRMessagingDelegate> remoteMessageDelegate
__deprecated_msg("Use 'delegate' property");
/**
* When set to `YES`, Firebase Messaging will automatically establish a socket-based, direct
* channel to the FCM server. Enable this only if you are sending upstream messages or
* receiving non-APNS, data-only messages in foregrounded apps.
* Default is `NO`.
*/
@property(nonatomic) BOOL shouldEstablishDirectChannel;
/**
* Returns `YES` if the direct channel to the FCM server is active, and `NO` otherwise.
*/
@property(nonatomic, readonly) BOOL isDirectChannelEstablished;
/**
* FIRMessaging
*
* @return An instance of FIRMessaging.
*/
+ (nonnull instancetype)messaging FIR_SWIFT_NAME(messaging());
/**
* Unavailable. Use +messaging instead.
*/
- (nonnull instancetype)init __attribute__((unavailable("Use +messaging instead.")));
#pragma mark - APNS
/**
* This property is used to set the APNS Token received by the application delegate.
*
* FIRMessaging uses method swizzling to ensure that the APNS token is set
* automatically. However, if you have disabled swizzling by setting
* `FirebaseAppDelegateProxyEnabled` to `NO` in your app's
* Info.plist, you should manually set the APNS token in your application
* delegate's `-application:didRegisterForRemoteNotificationsWithDeviceToken:`
* method.
*
* If you would like to set the type of the APNS token, rather than relying on
* automatic detection, see: `-setAPNSToken:type:`.
*/
@property(nonatomic, copy, nullable) NSData *APNSToken FIR_SWIFT_NAME(apnsToken);
/**
* Set APNS token for the application. This APNS token will be used to register
* with Firebase Messaging using `FCMToken` or
* `tokenWithAuthorizedEntity:scope:options:handler`.
*
* @param apnsToken The APNS token for the application.
* @param type The type of APNS token. Debug builds should use
* FIRMessagingAPNSTokenTypeSandbox. Alternatively, you can supply
* FIRMessagingAPNSTokenTypeUnknown to have the type automatically
* detected based on your provisioning profile.
*/
- (void)setAPNSToken:(nonnull NSData *)apnsToken type:(FIRMessagingAPNSTokenType)type;
#pragma mark - FCM Tokens
/**
* The FCM token is used to identify this device so that FCM can send notifications to it.
* It is associated with your APNS token when the APNS token is supplied, so that sending
* messages to the FCM token will be delivered over APNS.
*
* The FCM token is sometimes refreshed automatically. You can be notified of these changes
* via the FIRMessagingDelegate method `-message:didRefreshRegistrationToken:`, or by
* listening for the `FIRMessagingRegistrationTokenRefreshedNotification` notification.
*
* Once you have an FCM token, you should send it to your application server, so it can use
* the FCM token to send notifications to your device.
*/
@property(nonatomic, readonly, nullable) NSString *FCMToken FIR_SWIFT_NAME(fcmToken);
/**
* Retrieves an FCM registration token for a particular Sender ID. This can be used to allow
* multiple senders to send notifications to the same device. By providing a different Sender
* ID than your default when fetching a token, you can create a new FCM token which you can
* give to a different sender. Both tokens will deliver notifications to your device, and you
* can revoke a token when you need to.
*
* This registration token is not cached by FIRMessaging. FIRMessaging should have an APNS
* token set before calling this to ensure that notifications can be delivered via APNS using
* this FCM token. You may re-retrieve the FCM token once you have the APNS token set, to
* associate it with the FCM token. The default FCM token is automatically associated with
* the APNS token, if the APNS token data is available.
*
* @param senderID The Sender ID for a particular Firebase project.
* @param completion The completion handler to handle the token request.
*/
- (void)retrieveFCMTokenForSenderID:(nonnull NSString *)senderID
completion:(nonnull FIRMessagingFCMTokenFetchCompletion)completion
FIR_SWIFT_NAME(retrieveFCMToken(forSenderID:completion:));
/**
* Invalidates an FCM token for a particular Sender ID. That Sender ID cannot no longer send
* notifications to that FCM token.
*
* @param senderID The senderID for a particular Firebase project.
* @param completion The completion handler to handle the token deletion.
*/
- (void)deleteFCMTokenForSenderID:(nonnull NSString *)senderID
completion:(nonnull FIRMessagingDeleteFCMTokenCompletion)completion
FIR_SWIFT_NAME(deleteFCMToken(forSenderID:completion:));
#pragma mark - Connect
/**
* Create a FIRMessaging data connection which will be used to send the data notifications
* sent by your server. It will also be used to send ACKS and other messages based
* on the FIRMessaging ACKS and other messages based on the FIRMessaging protocol.
*
*
* @param handler The handler to be invoked once the connection is established.
* If the connection fails we invoke the handler with an
* appropriate error code letting you know why it failed. At
* the same time, FIRMessaging performs exponential backoff to retry
* establishing a connection and invoke the handler when successful.
*/
- (void)connectWithCompletion:(nonnull FIRMessagingConnectCompletion)handler
FIR_SWIFT_NAME(connect(handler:))
__deprecated_msg("Please use the shouldEstablishDirectChannel property instead.");
/**
* Disconnect the current FIRMessaging data connection. This stops any attempts to
* connect to FIRMessaging. Calling this on an already disconnected client is a no-op.
*
* Call this before `teardown` when your app is going to the background.
* Since the FIRMessaging connection won't be allowed to live when in the background, it is
* prudent to close the connection.
*/
- (void)disconnect
__deprecated_msg("Please use the shouldEstablishDirectChannel property instead.");
#pragma mark - Topics
/**
* Asynchronously subscribes to a topic.
*
* @param topic The name of the topic, for example, @"sports".
*/
- (void)subscribeToTopic:(nonnull NSString *)topic FIR_SWIFT_NAME(subscribe(toTopic:));
/**
* Asynchronously unsubscribe from a topic.
*
* @param topic The name of the topic, for example @"sports".
*/
- (void)unsubscribeFromTopic:(nonnull NSString *)topic FIR_SWIFT_NAME(unsubscribe(fromTopic:));
#pragma mark - Upstream
/**
* Sends an upstream ("device to cloud") message.
*
* The message is queued if we don't have an active connection.
* You can only use the upstream feature if your FCM implementation
* uses the XMPP server protocol.
*
* @param message Key/Value pairs to be sent. Values must be String, any
* other type will be ignored.
* @param receiver A string identifying the receiver of the message. For FCM
* project IDs the value is `SENDER_ID@gcm.googleapis.com`.
* @param messageID The ID of the message. This is generated by the application. It
* must be unique for each message generated by this application.
* It allows error callbacks and debugging, to uniquely identify
* each message.
* @param ttl The time to live for the message. In case we aren't able to
* send the message before the TTL expires we will send you a
* callback. If 0, we'll attempt to send immediately and return
* an error if we're not connected. Otherwise, the message will
* be queued. As for server-side messages, we don't return an error
* if the message has been dropped because of TTL; this can happen
* on the server side, and it would require extra communication.
*/
- (void)sendMessage:(nonnull NSDictionary *)message
to:(nonnull NSString *)receiver
withMessageID:(nonnull NSString *)messageID
timeToLive:(int64_t)ttl;
#pragma mark - Analytics
/**
* Use this to track message delivery and analytics for messages, typically
* when you receive a notification in `application:didReceiveRemoteNotification:`.
* However, you only need to call this if you set the `FirebaseAppDelegateProxyEnabled`
* flag to `NO` in your Info.plist. If `FirebaseAppDelegateProxyEnabled` is either missing
* or set to `YES` in your Info.plist, the library will call this automatically.
*
* @param message The downstream message received by the application.
*
* @return Information about the downstream message.
*/
- (nonnull FIRMessagingMessageInfo *)appDidReceiveMessage:(nonnull NSDictionary *)message;
@end