Constructor
- Properties
- Methods
- Related types
Constructor
The Ably Realtime library constructor is overloaded allowing it to be instantiated using a ClientOptions
object, or more simply using a string containing an API key or Token, as shown below:
new Ably.Realtime(ClientOptions clientOptions)Ably::Realtime.new(ClientOptions client_options)new io.ably.lib.AblyRealtime(ClientOptions clientOptions)new AblyRealtime(ClientOptions clientOptions)- (instancetype)initWithOptions:(ARTClientOptions *)options;init(options: ARTClientOptions)
This will instantiate the library using the specified ClientOptions.
This will instantiate the library and create a new Ably::Realtime::Client
using the specified ClientOptions
.
new Ably.Realtime(String keyOrTokenId)Ably::Realtime.new(String key_or_token_id)new io.ably.lib.AblyRealtime(String keyOrTokenIdString)new AblyRealtime(string key)- (instancetype)initWithKey:(NSString *)keyinit(key: String)
init(token: String)
This will instantiate the Realtime library with the provided API key or Token ID string.
The Realtime constructor is used to instantiate the library. The Realtime library may be instantiated multiple times with the same or different ClientOptions
in any given context. Except where specified otherwise, instances operate independently of one another.
Authentication
The Realtime library needs to have credentials to be able to authenticate with the Ably service. Ably supports both Basic and Token based authentication schemes. Read more on authentication.
Basic Authentication
You can pass a full-length API key in as ClientOptions#key
ClientOptions#Key
(or just straight into the constructor instead of a ClientOptions
instance), as obtained from the application dashboard. Use this option if you wish to use Basic authentication, or if you want to be able to request Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Note that initializing the library with a key
Key
does not necessarily mean that the library will use Basic auth; it is also able to create and sign Ably TokenRequests, and can use token authentication for itself if it needs to or if ClientOptions#useTokenAuth
is enabled.
Token Authentication
The ClientOptions#token
option takes a token
string or tokenDetails
object, which may have been obtained from some other instance that requested the Ably Token. This option is rarely used in production since tokens are short-lived, so generally you would not start with a token without the means to refresh it. The authUrl
and authCallback
AuthUrl
and AuthCallback
:auth_url
and :auth_callback
options allow the library to request new Ably-compatible tokens or Ably TokenRequests as it needs to; using these options allows the library to be instantiated without a key
or token
Key
or Token
, and an initial token will be obtained automatically when required.
Read more on authentication.
AblyRealtime PropertiesAbly.Realtime Propertiesio.ably.lib.AblyRealtime MembersAbly::Realtime::Client AttributesARTRealtime Properties
The Realtime client exposes the following public attributesmembersproperties:
authAuth
A reference to the Auth
authentication object configured for this client library.
channelsChannels
A reference to the Channel
collection instance for this library indexed by the channel name. See channels and messages for more information.
clientIdclient_idClientId
The client ID string, if any, configured for this client connection. See authentication for more information on authentication and using a client ID.
connectionConnection
A reference to the Connection
object for this library instance.
rest_client
A reference to the REST Client configured with the same ClientOptions
. The Realtime library is a super-set of the REST library, however accessing methods in the REST library, unlike the Realtime library, are blocking operations.
AblyRealtime MethodsAbly.Realtime Methodsio.ably.lib.AblyRealtime MethodsAbly::Realtime::Client MethodsARTRealtime Methods
connectConnect
connect()Deferrable connect → yields
Connection
void connect()void Connect()
Explicitly calling connect
is unnecessary unless the ClientOptions
autoConnect
auto_connect
AuthConnect
is disabled. This method calls connection.connect()
connection.connect
connection.Connect()
and causes the connection to open, entering the connecting
state.
Returns
A Deferrable
object is returned from this method.
On successfully connecting to Ably, the registered success callbacks for the Deferrable
and any block provided to this method yields a Connection
object.
Failure to connect will trigger the errback callbacks of the Deferrable
with an ErrorInfo
object containing an error response as defined in the Ably REST API documentation.
closeClose
close()Deferrable close → yields
Connection
void close()void Close()
This calls connection.close()
connection.close
connection.Close()
and causes the connection to close, entering the closing
state. Once closed
, the library will not attempt to re-establish the connection without an explicit call to connect()
connect
Connect()
.
Returns
A Deferrable
object is returned from this method.
On successfully closing the connection, the registered success callbacks for the Deferrable
and any block provided to this method yields a Connection
object.
Failure to close the connection will trigger the errback callbacks of the Deferrable
with an ErrorInfo
object containing an error response as defined in the Ably REST API documentation.
statsStats
stats(Object options, callback(ErrorInfo err, PaginatedResult<Stats> results))Deferrable stats(Hash options) → yields PaginatedResult<Stats>PaginatedResult<Stats> stats(Param[] options)stats(query: ARTStatsQuery?, callback: (ARTPaginatedResult<ARTStats>?, ARTErrorInfo?) → Void) throwsTask<PaginatedResult<Stats>> StatsAsync(StatsRequestParams query)
This call queries the REST /stats
API and retrieves your application’s usage statistics. A PaginatedResult is returned, containing an array of Stats for the first page of results. PaginatedResult objects are iterable providing a means to page through historical statistics. See an example set of raw stats returned via the REST API.
See statistics for more information.
Parameters
- optionsquery
- an optional objectHash
ARTStatsQuery
StatsRequestParams
Param
[] array containing the query parameters
- callback
- is a function of the form:
function(err, result)
- &block
- yields a
PaginatedResult<Stats>
object - callback
- called with a ARTPaginatedResult<ARTStats> object or an error
options
parametersARTStatsQuery
propertiesStatsRequestParams
properties
The following options, as defined in the REST /stats
API endpoint, are permitted:
- start:startStart
-
beginning of time earliest
DateTimeOffset
orTime
or time in milliseconds since the epoch for any stats retrieved
Type:Long
Int or @Time
DateTimeOffset
- end:endEnd
-
current time latest
DateTimeOffset
orTime
or time in milliseconds since the epoch for any stats retrieved
Type:Long
Int or @Time
DateTimeOffset
- direction:directionDirection
-
backwards
:
forwards
or:
backwards
Type:String
Symbol
Direction
enum - limit:limitLimit
-
100 maximum number of stats to retrieve up to 1,000
Type:Integer
- unit:unitUnit
-
minute
:
minute
,:
hour
,:
day
or:
month
. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query
Type:String
ARTStatsGranularity
Symbol
StatsIntervalGranularity
enum
Callback result
On success, result
contains a PaginatedResult
encapsulating an array of Stats
objects corresponding to the current page of results. PaginatedResult
supports pagination using next
and first
methods.
On failure to retrieve stats, err
contains an ErrorInfo
object with an error response as defined in the Ably REST API documentation.
Returns
On success, the returned PaginatedResult
encapsulates an array of Stats
objects corresponding to the current page of results. PaginatedResult
supports pagination using next
and first
methods.
Failure to retrieve the stats will raise an AblyException
Returns
Returns a Task<PaginatedResult>
which needs to be awaited.
On success, the returned PaginatedResult
encapsulates an array of Stats
objects corresponding to the current page of results. PaginatedResult
supports pagination using NextAsync
and FirstAsync
methods.
Failure to retrieve the stats will raise an AblyException
Returns
A Deferrable
object is returned from the stats method.
On success, the registered success callbacks for the Deferrable
and any block provided to the method yields a PaginatedResult that encapsulates an array of Stats
objects corresponding to the current page of results. PaginatedResult
supports pagination using next
and first
methods.
Failure to retrieve the stats will trigger the errback callbacks of the Deferrable
with an ErrorInfo
object containing an error response as defined in the Ably REST API documentation.
timeTime
time(callback(ErrorInfo err, Number time))Deferrable time → yields Timelong time()Task
TimeAsync() time(callback: (NSDate?, NSError?) → Void)
Obtains the time from the Ably service as a Time
objecta DateTimeOffset
objectmilliseconds since epoch. (Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably TokenRequests with a more accurate timestamp should use the queryTime
clientOptions instead of this method).
Callback result
On success, time
is a number containing the number of milliseconds since the epoch.
On failure to retrieve the Ably server time, err
contains an ErrorInfo
object with an error response as defined in the Ably REST API documentation.
Returns
On success, milliseconds since the epoch is returned.
Failure to retrieve the Ably server time will raise an AblyException
.
Returns
A Task<DateTimeOffset>
is returned from this method.
When awaited on success it will return the server time converted to a DateTimeOffset
.
Failure to retrieve the Ably server time will raise an AblyException
.
Returns
A Deferrable
object is returned from this method.
On success, the registered success callbacks for the Deferrable
and any block provided to the method yields a Time
object.
Failure to retrieve the Ably server time will trigger the errback callbacks of the Deferrable
with an ErrorInfo
object containing an error response as defined in the Ably REST API documentation.
request
request(String method, String path, Object params, Object body, Object headers, callback(ErrorInfo err, HttpPaginatedResponse results))HttpPaginatedResponse request(String method, String path, Object params, Object body, Object headers)publish(method=String, path=String, params=Object, body=Object, headers=Object)HttpPaginatedResponse request(String method, String path, Object params, Object body, Object headers)request(method: String, path: String, params: Object?, body: Object?, headers: Object?, callback: (ARTHttpPaginatedResponse, ARTErrorInfo?) → Void)
Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to handle authentication, paging, fallback hosts, MsgPack and JSON support, etc. themselves.
Parameters
- method
- either
get
,post
,put
,patch
ordelete
.
Type: String - path
- the path to query.
Type: String - params
- (optional) any querystring parameters needed.
Type: Object - body
- (optional; for
post
,put
andpatch
methods) the body of the request, as anything that can be serialized into JSON, such as anObject
orArray
.
Type: Serializable - headers
- (optional) any headers needed. If provided, these will be mixed in with the default library headers.
Type: Object
Callback result
On success, results
contains an HttpPaginatedResponse
ARTHttpPaginatedResponse
containing the statusCode
and a success
boolean, headers
, and an items
array containing the current page of results. It supports pagination using next
and first
methods, identically to PaginatedResult
. (Note that for javascript, if the request fails, the callback will have an err
rather results
, so the success
boolean is not really used))
On failure, err
contains an ErrorInfo
object with an error response as defined in the Ably REST API documentation.
Returns
On success, the returned HttpPaginatedResponse
contains a status_code
statusCode
and a success
boolean, headers
, and an items
array containing the current page of results. It supports pagination using next
and first
methods, identically to PaginatedResult
.
Failure to retrieve the message history will raise an AblyException
Returns
The method is asynchronous and return a Task that has to be awaited to get the result.
On success, the returned HttpPaginatedResponse
containing the StatusCode
and a Success
boolean, Headers
, and an Items
array containing the current page of results. HttpPaginatedResponse
supports pagination using NextAsync
and FirstAsync
methods.
Failure to retrieve the message history will raise an AblyException
Example
rest.request(
'get',
'/channels/someChannel/messages',
{limit: 1, direction: 'forwards'},
null,
null,
function(err, response) {
if(err) {
console.log('An error occurred; err = ' + err.toString());
} else {
console.log('Success! status code was ' + response.statusCode);
console.log(response.items.length + ' items returned');
if(response.hasNext()) {
response.next(function(err, nextPage) {
console.log(nextPage.items.length + ' more items returned');
});
}
}
});
rest.request(
'get',
'/channels/someChannel/messages',
{limit: 1, direction: 'forwards'},
null,
null,
function(err, response) {
if(err) {
console.log('An error occurred; err = ' + err.toString());
} else {
console.log('Success! status code was ' + response.statusCode);
console.log(response.items.length + ' items returned');
if(response.hasNext()) {
response.next(function(err, nextPage) {
console.log(nextPage.items.length + ' more items returned');
});
}
}
});
Related types
ClientOptionsARTClientOptionsio.ably.types.ClientOptionsIO.Ably.ClientOptions
ClientOptions
is a plain JavaScript object and is used in the Ably.Realtime
constructor’s options
argument. The following attributes can be defined on the object:
ClientOptions
is a Hash object and is used in the Ably::Realtime
constructor’s options
argument. The following key symbol values can be added to the Hash:
ClientOptions
is a associative array and is used in the Ably\AblyRealtime
constructor’s options
argument. The following named keys and values can be added to the associative array:
ART
ClientOptions
is used in the AblyRealtime
constructor’s options
argument.
ClientOptions
is a plain JavaScript object and is used in the Ably.Realtime
constructor’s options
argument. The following attributes can be defined on the object:
ClientOptions
is a Hash object and is used in the Ably::Realtime
constructor’s options
argument. The following key symbol values can be added to the Hash:
ClientOptions
is a associative array and is used in the Ably\AblyRest
constructor’s options
argument. The following named keys and values can be added to the associative array:
ART
ClientOptions
is used in the AblyRealtime
constructor’s options
argument.
PropertiesMembersAttributesKeyword arguments
- keyKey:key
- The full key string, as obtained from the application dashboard. Use this option if you wish to use Basic authentication, or wish to be able to issue Ably Tokens without needing to defer to a separate entity to sign Ably TokenRequests. Read more about Basic authentication
Type:String
- tokenToken:token
- An authenticated token. This can either be a
TokenDetails
object, aTokenRequest
object, or token string (obtained from thetoken
Token
property of aTokenDetails
component of an Ably TokenRequest response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such asauthUrl
AuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Read more about Token authentication
Type:String
,TokenDetails
orTokenRequest
- tokenDetailsTokenDetailstoken_details:token_details
- An authenticated
TokenDetails
object (most commonly obtained from an Ably Token Request response). This option is mostly useful for testing: since tokens are short-lived, in production you almost always want to use an authentication method that allows the client library to renew the token automatically when the previous one expires, such asauthUrl
AuthUrl:auth_urlauth_url or authCallbackAuthCallbackauth_callback:auth_callback. Use this option if you wish to use Token authentication. Read more about Token authentication
Type:TokenDetails
- tlsTls:tls
-
true A boolean value, indicating whether or not a TLS (“SSL”) secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. Find out more about TLS
Type:Boolean
- clientIdClientIdclient_id:client_id
- A client ID, used for identifying this client when publishing messages or for presence purposes. The
clientId
client_id
ClientId
can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that aclientId
client_id
ClientId
may also be implicit in a token used to instantiate the library; an error will be raised if aclientId
client_id
specified here conflicts with theclientId
client_id
ClientId
implicit in the token. Find out more about client identities
Type:String
- authCallbackAuthCallbackauth_callback:auth_callback
- A functionfunction with the form
function(tokenParams, callback(err, tokenOrTokenRequest))
TokenCallback
instancecallable (eg a lambda)proc / lambda (called synchronously in REST and Realtime but does not block EventMachine in the latter) which is called when a new token is required. The role of the callback is to either generate a signedTokenRequest
which may then be submitted automatically by the library to the Ably REST APIrequestToken
; or to provide a valid token in as aTokenDetails
object. See an authentication callback example or our authentication documentation for details of the Ably Token request format and associated API calls. Please note that the JSON stringified version ofTokenDetails
orTokenRequest
must be less than 128KiB.
Type:Callable
TokenCallback
Proc
Func<TokenParams, Task<TokenDetails>>
- authUrlAuthUrlauth_url:auth_url
- A URL that the library may use to obtain a token string (in plain text format), or a signed
TokenRequest
orTokenDetails
(in JSON format). For example, this can be used by a client to obtain signed Ably TokenRequest from an application server. Please note that the JSON stringified version ofTokenDetails
orTokenRequest
must be less than 128KiB.
Type:String
Uri
- authMethodAuthMethodauth_method:auth_method
-
GET
:get
The HTTP verb to use for the request, eitherGET
:get
orPOST
:post
Type:String
Symbol
HttpMethod
- authHeadersAuthHeadersauth_headers:auth_headers
- A set of key value pair headers to be added to any request made to the
authUrl
AuthUrl
. Useful when an application requires these to be added to validate the request or implement the response. If theauthHeaders
object contains anauthorization
key, thenwithCredentials
will be set on the xhr request.
Type:Object
Dict
Hash
Associative Array
Param []
Dictionary<string, string>
- authParamsAuthParamsauth_params:auth_params
- A set of key value pair params to be added to any request made to the
authUrl
AuthUrl
. When theauthMethod
AuthMethod
isGET
, query params are added to the URL, whereas whenauthMethod
AuthMethod
isPOST
, the params are sent as URL encoded form data. Useful when an application require these to be added to validate the request or implement the response.
Type:Object
Dict
Hash
Associative Array
Param []
Dictionary<string, string>
- useTokenAuthUseTokenAuthuse_token_auth:use_token_auth
-
false When true, forces Token authentication to be used by the library. Please note that if a
client_id
clientId
is not specified in theClientOptions
orTokenParams
, then the Ably Token issued will be anonymous.
Type:Boolean
- environmentEnvironment:environment
-
nullNullNonenil Allows a custom environment, region or cluster to be used with the Ably service. Please contact us if you require a custom environment. Note that once a custom environment is specified, the fallback host functionality is disabled by default.
Type:String
- fallbackHostsFallbackHostsfallback_hosts:fallback_hosts
-
[a.ably-realtime.com, b.ably-realtime.com, c.ably-realtime.com, d.ably-realtime.com, e.ably-realtime.com]
An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host.
When a custom environment is specified, the fallback host functionality is disabled. If your customer success manager has provided you with a set of custom fallback hosts, please specify them here.
Type:String []
- fallbackHostsUseDefaultFallbackHostsUseDefaultfallback_hosts_use_default:fallback_hosts_use_default
-
true When true, the client will use fallback hosts in the case of an error necessitating the use of an alternative host. When a custom environment is specified, by default the fallback host functionality is disabled. Before setting this to true, please check with your customer success manager if this is supported for your environment.
Type:Boolean
- log
- Parameters to control the log output of the library. The supplied value must be an object that may contain one or both of the following entries:
-
level
: a number controlling the verbosity of the output. Valid values are: 0 (no logs), 1 (errors only), 2 (errors plus connection and channel state changes), 3 (high-level debug output), and 4 (full debug output). -
handler
: a function to handle each line of log output. Ifhandler
is not specified,console.log
is used.
Note that the log level and log handler have global scope in the library and will thus not act independently between library instances when multiple library instances exist concurrently.
Type:Object
-
- transports
- An optional array of transports to use, in descending order of preference. In the browser environment the available transports are:
web_socket
,xhr
,jsonp
.The transports available in the Node.js client library are:web_socket
,xhr
,comet
.
Type:String []
- logLevel
-
5 A number controlling the verbosity of the output from 2 (maximum, verbose) to 6 (errors only). A special value of 99 will silence all logging. Note that the
logLevel
is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently.
Type:Integer
- logHandler
-
System.out PrintStream
ALogHandler
interface can be specified to handle each line of log output. IflogHandler
is not specified,System.out
is used. Note that thelogHandler
is a static variable in the library and will thus not act independently between library instances when multiple library instances exist concurrently.
Type: PrintStream
To set the log level and custom logger sink when using the .NET library, configure the static IO.Ably.Logger
class or specify the ClientOptions
:
- LogLevel
-
Error
This is an enum controlling the verbosity of the output fromDebug
(maximum) toError
(errors only). A special value ofNone
will silence all logging. Note that theLogLevel
is a static variable in the library and will thus not act independently between library instances.
Type:Enum
- LoggerSink
-
IO.Ably.DefaultLoggerSink
The default ILoggerSink outputs messages to the debug console. This property allows the user to pipe the log messages to their own logging infrastructure.
- logLevel
-
ARTLogLevelWarn An enum controlling the verbosity of the output from
ARTLogLevelVerbose
toARTLogLevelNone
. A special value of 99 will silence all logging.
Type:ARTLogLevel
- logHandler
- A
ARTLog
object can be specified to handle each line of log output. IflogHandler
is not specified, a defaultARTLog
instance is used.
Type:ARTLog *
- :log_level
-
:error
Log level for the standard Logger that outputs toSTDOUT
. Can be set to:fatal
,:error
,:warn
,:info
,:debug
or:none
. Alternatively aLogger
severity constant can be specified.
Type:Symbol
,Logger::SEVERITY
- :logger
-
STDOUT Logger
A RubyLogger
compatible object to handle each line of log output. Iflogger
is not specified,STDOUT
is used.
Type: Ruby @Logger
- logLevel
-
Log::WARNING
A number controlling the verbosity of the output from 1 (minimum, errors only) to 4 (most verbose);
Type:Integer
- logHandler
-
console.log
A function to handle each line of log output. If handler is not specified,console.log
is used. Note that the log level and log handler have global scope in the library and will therefore not act independently between library instances when multiple library instances exist concurrently.
Type:Function
- useBinaryProtocolUseBinaryProtocoluse_binary_protocol:use_binary_protocol
-
false If set to true, will enable the binary protocol (MessagePack) if it is supported. It’s disabled by default on browsers for performance considerations (browsers are optimized for decoding JSON)true If set to false, will forcibly disable the binary protocol (MessagePack). The binary protocol is used by default unless it is not supportedNote: The binary protocol is currently not supported in Swiftin Objective-Cin PHP. Find out more about the benefits of binary encoding
Type:Boolean
- queueMessagesQueueMessages:queue_messages
-
true If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior allows applications to submit messages immediately upon instancing 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 under those conditions
Type:Boolean
- echoMessagesEchoMessages:echo_messages
-
true If false, prevents messages originating from this connection being echoed back on the same connection
Type:Boolean
- autoConnectAutoConnect:auto_connect
-
true By default as soon as the client library is instantiated it will connect to Ably. You can optionally set this to false and explicitly connect to Ably when require using the
connect
method
Type:Boolean
- recover
- This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might typically be used by clients of the browser library to ensure connection state can be preserved when the user refreshes the page. A recovery key string can be explicitly provided, or alternatively if a callback function is provided, the client library will automatically persist the recovery key between page reloads and call the callback when the connection is recoverable. The callback is then responsible for confirming whether the connection should be recovered or not. See connection state recovery for further information
Type:String
,Callable
- closeOnUnload
-
true When true, the client library will automatically send a close request to Ably whenever the
window beforeunload
event fires. By enabling this option, the close request sent to Ably ensures the connection state will not be retained and all channels associated with the channel will be detached. This is commonly used by developers who want presence leave events to fire immediately i.e. if a user navigates to another page or closes their browser, then enabling this option will result in the presence member leaving immediately. Without this option or an explicit call to theclose
method of theConnection object
, Ably expects that the abruptly disconnected connection could later be recovered and therefore does not immediately remove the user from presence. Instead, to avoid “twitchy” presence behavior an abruptly disconnected client is removed from channels in which they are present after 15 seconds, and the connection state is retained for two minutes
Type:Boolean
- recoverRecover:recover
- This option allows a connection to inherit the state of a previous connection that may have existed under a different instance of the library by providing that connection’s
recoveryKey
recovery_key
. This might typically be used by clients of an app to ensure connection state can be preserved following a reload. See connection state recovery for further information and example code
Type:String
- queryTimeQueryTime:query_time
-
false If true, the library will query the Ably servers for the current time instead of relying on a locally-available time of day. Knowing the time accurately is needed to create valid signed Ably Token Requests, so this option is useful for library instances on auth servers if the server clock is insufficiently accurate. The server is queried only once per client library instance, and used to calculate and store the offset from the local clock.
Type:Boolean
- defaultTokenParamsDefaultTokenParams:default_token_params
- When a TokenParams object is provided, it will override the client library defaults when issuing new Ably Tokens or Ably TokenRequests
Type:TokenParams
- disconnectedRetryTimeoutDisconnectedRetryTimeout:disconnected_retry_timeout
-
15,000ms15s When the connection enters the
DISCONNECTED
state, after this delay in millisecondsin secondsas aNSTimeInterval
, if the state is stillDISCONNECTED
, the client library will attempt to reconnect automatically
Type:Integer
NSTimeInterval
- suspendedRetryTimeoutSuspendedRetryTimeout:suspended_retry_timeout
-
30,000ms30s When the connection enters the
SUSPENDED
state, after this delay in millisecondsin secondsas aNSTimeInterval
, if the state is stillSUSPENDED
, the client library will attempt to reconnect automatically
Type:Integer
NSTimeInterval
Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsIO.Ably.Stats
A Stats
object represents a application statistic for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our statistics API as well as your application dashboard.
Please note that most attributes of the Stats
type below contain references to further stats types. This documentation is not exhaustive for all stats types, and as such, links to the stats types below will take you to the Ruby library stats documentation which contains exhaustive stats documentation. Ruby and Python however uses under_score
case instead of the default camelCase
in most languages, so please bear that in mind.
PropertiesMembersAttributesKeyword arguments
- unit
- the length of the interval that this statistic covers, such as
:minute
,:hour
,:day
,:month
Minute
,Hour
,Day
,Month
'minute'
,'hour'
,'day'
,'month'
.
Type:Stats::GRANULARITY
StatsIntervalGranularity enum
ARTStatsGranularity
String
- interval_granularityintervalGranularity
- Deprecated alias for
unit
; scheduled to be removed in version 2.x client library versions.
Type:Stats::GRANULARITY
StatsIntervalGranularity enum
ARTStatsGranularity
String
- intervalIdinterval_idIntervalId
- the UTC time at which the time period covered by this
Stats
object starts. For example, an interval ID value of “2018-03-01:10” in aStats
object whoseunit
isday
would indicate that the period covered is “2018-03-01:10 .. 2018-03-01:11”. AllStats
objects, except those whoseunit
isminute
, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer theunit
by looking at the resolution of theintervalId
.Stats
objects covering an individual minute will have an interval ID indicating that time; for example “2018-03-01:10:02”.
Type:String
- interval_timeIntervalTime
- A
Time
DateTime
DateTimeOffset
object representing the parsedintervalId
interval_id
IntervalId
(the UTC time at which the time period covered by thisStats
object starts)
Type:Time
DateTime
DateTimeOffset
- allAll
- aggregate count of both
inbound
andoutbound
message stats
Type:MessageTypes
- apiRequestsapi_requestsApiRequests
- breakdown of API requests received via the Ably REST API
Type: RequestCount - channelsChannels
- breakdown of channel related stats such as min, mean and peak channels
Type:ResourceCount
- connectionsConnections
- breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections
Type:ConnectionTypes
- inboundInbound
- statistics such as count and data for all inbound messages received over REST and Realtime connection, organized into normal channel messages or presence messages
Type:MessageTraffic
- outboundOutbound
- statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with WebHooks, organized into normal channel messages or presence messages
Type:MessageTraffic
- persistedPersisted
- messages persisted and later retrieved via the history API
Type:MessageTypes
- tokenRequeststoken_requestsTokenRequests
- breakdown of Ably Token requests received via the Ably REST API.
Type:RequestCount
- pushPush
- Detailed stats on push notifications, see our Push documentation for more details
Type:PushStats
ARTStatsGranularity
ARTStatsGranularity
is an enum specifying the granularity of a ARTStats interval
.
typedef NS_ENUM(NSUInteger, ARTStatsGranularity) {
ARTStatsGranularityMinute,
ARTStatsGranularityHour,
ARTStatsGranularityDay,
ARTStatsGranularityMonth
};
enum ARTStatsGranularity : UInt {
case Minute
case Hour
case Day
case Month
}
StatsIntervalGranularity
is an enum specifying the granularity of a Stats interval
.
public enum StatsGranularity
{
Minute,
Hour,
Day,
Month
}
HttpPaginatedResponse
An HttpPaginatedResponse
is a superset of PaginatedResult
, which is a type that represents a page of results plus metadata indicating the relative queries available to it. HttpPaginatedResponse
additionally carries information about the response to an HTTP request. It is used when making custom HTTP requests.
PropertiesMembersAttributesAttributes
- itemsItems
- contains a page of results (for example an Array of
Message
orPresenceMessage
objects for a channel history request).
Type:Array<>
Type:List<>
- statusCodestatus_codeStatusCode
- the HTTP status code of the response
Type: Number - successSuccess
- whether that HTTP status code indicates success (equivalent to
200 <= statusCode < 300
)
Type: Boolean - headersHeaders
- the response’s headers
Type: Object
Methods
firstFirst
first(callback(ErrorInfo err, HttpPaginatedResponse resultPage))HttpPaginatedResponse firstHttpPaginatedResponse first()HttpPaginatedResponse first()Task<HttpPaginatedResponse
> FirstAsync() HttpPaginatedResponse first()first(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) → Void)
Returns a new HttpPaginatedResponse
for the first page of results. When using the Realtime library, the first
method returns a Deferrable and yields an HttpPaginatedResponse
.The method is asynchronous and returns a Task which needs to be awaited to get the @HttpPaginatedResponse":/api/realtime-sdk/types#http-paginated-response.
hasNextHasNexthas_next?has_next
Boolean hasNext()Boolean has_next?Boolean hasNext()Boolean has_next()Boolean HasNext()Boolean hasNext()Boolean hasNext()
Returns true
if there are more pages available by calling next
Next
and returns false
if this page is the last page available.
isLastIsLastlast?is_last
Boolean isLast()Boolean last?Boolean isLast()Boolean is_last()Boolean IsLast()Boolean isLast()Boolean isLast()
Returns true
if this page is the last page and returns false
if there are more pages available by calling next
Next
available.
nextNext
next(callback(ErrorInfo err, HttpPaginatedResponse resultPage))HttpPaginatedResponse nextHttpPaginatedResponse next()HttpPaginatedResponse next()Task<HttpPaginatedResponse
> NextAsync() HttpPaginatedResponse next()next(callback: (ARTHttpPaginatedResponse?, ARTErrorInfo?) → Void)
Returns a new HttpPaginatedResponse
loaded with the next page of results. If there are no further pages, then null
a blank HttpPaginatedResponse will be returnedNull
None
nil
is returned. The method is asynchronous and return a Task which needs to be awaited to get the HttpPaginatedResponse
When using the Realtime library, the first
method returns a Deferrable and yields an HttpPaginatedResponse.
Example
The HttpPaginatedResponse
interface is a superset of PaginatedResult
, see the PaginatedResult
example
io.ably.lib.types.Param
Param
is a type encapsulating a key/value pair. This type is used frequently in method parameters allowing key/value pairs to be used more flexible, see Channel#history
for an example.
Please note that key
and value
attributes are always strings. If an Integer
or other value type is expected, then you must coerce that type into a String
.
Members
- key
- The key value
Type:String
- value
- The value associated with the
key
Type:String