ARTClientOptions

Objective-C

@interface ARTClientOptions : ARTAuthOptions

Swift

class ARTClientOptions : ARTAuthOptions

Passes additional client-specific properties to the REST -[ARTRestProtocol initWithOptions:] or the Realtime -[ARTRealtimeProtocol initWithOptions:].

  • Enables a non-default Ably host to be specified. For development environments only. The default value is rest.ably.io.

    Declaration

    Objective-C

    @property (nonatomic) NSString *_Nonnull restHost;

    Swift

    var restHost: String { get set }

  • Enables a non-default Ably host to be specified for realtime connections. For development environments only. The default value is realtime.ably.io.

    Declaration

    Objective-C

    @property (nonatomic) NSString *_Nonnull realtimeHost;

    Swift

    var realtimeHost: String { get set }

  • Enables a non-default Ably port to be specified. For development environments only. The default value is 80.

    Declaration

    Objective-C

    @property (nonatomic) NSInteger port;

    Swift

    var port: Int { get set }

  • Enables a non-default Ably TLS port to be specified. For development environments only. The default value is 443.

    Declaration

    Objective-C

    @property (nonatomic) NSInteger tlsPort;

    Swift

    var tlsPort: Int { get set }

  • Enables a custom environment to be used with the Ably service.

    Declaration

    Objective-C

    @property (nonatomic) NSString *_Nonnull environment;

    Swift

    var environment: String { get set }
  • tls

    When false, the client will use an insecure connection. The default is true, meaning a TLS connection will be used to connect to Ably.

    Declaration

    Objective-C

    @property (nonatomic) BOOL tls;

    Swift

    var tls: Bool { get set }

  • Controls the log output of the library. This is an object to handle each line of log output.

    Declaration

    Objective-C

    @property (nonatomic) ARTLog *_Nonnull logHandler;

    Swift

    var logHandler: ARTLog { get set }

  • Controls the verbosity of the logs output from the library. Levels include ARTLogLevelVerbose, ARTLogLevelDebug, ARTLogLevelInfo, ARTLogLevelWarn and ARTLogLevelError.

    Declaration

    Objective-C

    @property (nonatomic) ARTLogLevel logLevel;

    Swift

    var logLevel: ARTLogLevel { get set }

  • If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior enables applications to submit messages immediately upon instantiating the library without having to wait for the connection to be established. Applications may use this option to disable queueing if they wish to have application-level control over the queueing. The default is true.

    Declaration

    Objective-C

    @property (nonatomic) BOOL queueMessages;

    Swift

    var queueMessages: Bool { get set }

  • If false, prevents messages originating from this connection being echoed back on the same connection. The default is true.

    Declaration

    Objective-C

    @property (nonatomic) BOOL echoMessages;

    Swift

    var echoMessages: Bool { get set }

  • When true, the more efficient MsgPack binary encoding is used. When false, JSON text encoding is used. The default is true.

    Declaration

    Objective-C

    @property (nonatomic) BOOL useBinaryProtocol;

    Swift

    var useBinaryProtocol: Bool { get set }

  • When true, the client connects to Ably as soon as it is instantiated. You can set this to false and explicitly connect to Ably using the -[ARTConnectionProtocol connect] method. The default is true.

    Declaration

    Objective-C

    @property (nonatomic) BOOL autoConnect;

    Swift

    var autoConnect: Bool { get set }

  • Enables a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might happen upon the app restart where a recovery key string can be explicitly provided to the -[ARTRealtimeProtocol initWithOptions:] initializer. See connection state recovery for further information.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) NSString *recover;

    Swift

    var recover: String? { get set }

  • A client ID, used for identifying this client when publishing messages or for presence purposes. The clientId can be any non-empty string, except it cannot contain a *. This option is primarily intended to be used in situations where the library is instantiated with a key. Note that a clientId may also be implicit in a token used to instantiate the library. An error will be raised if a clientId specified here conflicts with the clientId implicit in the token.

    Declaration

    Objective-C

    @property (nonatomic, nullable) NSString *clientId;

    Swift

    var clientId: String? { get set }

  • When a ARTTokenParams object is provided, it overrides the client library defaults when issuing new Ably Tokens or Ably ARTTokenRequests.

    Declaration

    Objective-C

    @property (nonatomic, nullable) ARTTokenParams *defaultTokenParams;

    Swift

    var defaultTokenParams: ARTTokenParams? { get set }

  • If the connection is still in the ARTRealtimeConnectionState.ARTRealtimeDisconnected state after this delay, the client library will attempt to reconnect automatically. The default is 15 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval disconnectedRetryTimeout;

    Swift

    var disconnectedRetryTimeout: TimeInterval { get set }

  • When the connection enters the ARTRealtimeConnectionState.ARTRealtimeSuspended state, after this delay, if the state is still ARTRealtimeConnectionState.ARTRealtimeSuspended, the client library attempts to reconnect automatically. The default is 30 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval suspendedRetryTimeout;

    Swift

    var suspendedRetryTimeout: TimeInterval { get set }

  • When a channel becomes ARTRealtimeChannelState.ARTRealtimeChannelSuspended following a server initiated ARTRealtimeChannelState.ARTRealtimeChannelDetached, after this delay, if the channel is still ARTRealtimeChannelState.ARTRealtimeChannelSuspended and the connection is ARTRealtimeConnectionState.ARTRealtimeConnected, the client library will attempt to re-attach the channel automatically. The default is 15 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval channelRetryTimeout;

    Swift

    var channelRetryTimeout: TimeInterval { get set }

  • Timeout for opening a connection to Ably to initiate an HTTP request. The default is 4 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval httpOpenTimeout;

    Swift

    var httpOpenTimeout: TimeInterval { get set }

  • Timeout for a client performing a complete HTTP request to Ably, including the connection phase. The default is 10 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval httpRequestTimeout;

    Swift

    var httpRequestTimeout: TimeInterval { get set }

  • The maximum time before HTTP requests are retried against the default endpoint. The default is 600 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval fallbackRetryTimeout;

    Swift

    var fallbackRetryTimeout: TimeInterval { get set }

  • The maximum number of fallback hosts to use as a fallback when an HTTP request to the primary host is unreachable or indicates that it is unserviceable. The default value is 3.

    Declaration

    Objective-C

    @property (nonatomic) NSUInteger httpMaxRetryCount;

    Swift

    var httpMaxRetryCount: UInt { get set }

  • The maximum elapsed time in which fallback host retries for HTTP requests will be attempted. The default is 15 seconds.

    Declaration

    Objective-C

    @property (nonatomic) NSTimeInterval httpMaxRetryDuration;

    Swift

    var httpMaxRetryDuration: TimeInterval { get set }

  • An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. If you have been provided a set of custom fallback hosts by Ably, please specify them here.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) NSArray<NSString *> *fallbackHosts;

    Swift

    var fallbackHosts: [String]? { get set }

  • Deprecated

    Future library releases will ignore any supplied value.

    DEPRECATED: this property is deprecated and will be removed in a future version. Enables default fallback hosts to be used.

    Declaration

    Objective-C

    @property (nonatomic) BOOL fallbackHostsUseDefault;

    Swift

    var fallbackHostsUseDefault: Bool { get set }

  • DEPRECATED: this property is deprecated and will be removed in a future version. Defaults to a string value for an Ably error reporting DSN (Data Source Name), which is typically a URL in the format https://[KEY]:[SECRET]@errors.ably.io/[ID]. When set to nil exception reporting is disabled.

    Declaration

    Objective-C

    @property (nonatomic, nullable) NSString *logExceptionReportingUrl;

    Swift

    var logExceptionReportingUrl: String? { get set }

  • The queue to which all calls to user-provided callbacks will be dispatched asynchronously. It will be used as target queue for an internal, serial queue.

    It defaults to the main queue.

    Declaration

    Objective-C

    @property (nonatomic) dispatch_queue_t _Nonnull dispatchQueue;

    Swift

    var dispatchQueue: dispatch_queue_t { get set }

  • The queue to which all internal concurrent operations will be dispatched. It must be a serial queue. It shouldn’t be the same queue as dispatchQueue.

    It defaults to a newly created serial queue.

    Declaration

    Objective-C

    @property (nonatomic) dispatch_queue_t _Nonnull internalDispatchQueue;

    Swift

    var internalDispatchQueue: dispatch_queue_t { get set }

  • When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. The default is true.

    Declaration

    Objective-C

    @property (nonatomic) BOOL idempotentRestPublishing;

    Swift

    var idempotentRestPublishing: Bool { get set }

  • When true, every REST request to Ably should include a random string in the request_id query string parameter. The random string should be a url-safe base64-encoding sequence of at least 9 bytes, obtained from a source of randomness. This request ID must remain the same if a request is retried to a fallback host. Any log messages associated with the request should include the request ID. If the request fails, the request ID must be included in the ARTErrorInfo returned to the user. The default is false.

    Declaration

    Objective-C

    @property (nonatomic) BOOL addRequestIds;

    Swift

    var addRequestIds: Bool { get set }

  • A set of key-value pairs that can be used to pass in arbitrary connection parameters, such as heartbeatInterval or remainPresentFor.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) NSDictionary<NSString *, ARTStringifiable *> *transportParams;

    Swift

    var transportParams: [String : ARTStringifiable]? { get set }

  • The object that processes Push activation/deactivation-related actions.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<ARTPushRegistererDelegate, NSObject> pushRegistererDelegate;

    Swift

    weak var pushRegistererDelegate: (NSObjectProtocol & ARTPushRegistererDelegate)? { get set }

  • A set of additional entries for the Ably agent header. Each entry can be a key string or set of key-value pairs. This should only be used by Ably-authored SDKs. If an agent does not have a version, represent this by using the ARTClientInformationAgentNotVersioned pointer as the version.

    Declaration

    Objective-C

    @property (nonatomic, copy, nullable) NSDictionary<NSString *, NSString *> *agents;

    Swift

    var agents: [String : String]? { get set }