Class: HeapAPI::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/heap/client.rb,
lib/heap/validations.rb

Overview

Internal methods used to validate API input.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Creates a new client for the Heap server-side API.

For simplicity, consider using the global client instance referenced by the Heap constant instead of creating and managing new instances.

Parameters:

  • options (Hash<Symbol, Object>) (defaults to: {}) —

    initial values for attributes

Options Hash (options):

  • app_id (String) —

    the Heap application ID from heapanalytics.com/app/install

  • js_options (Hash<Symbol, Object>) —

    default heap.js advanced options

  • stubbed (Boolean) —

    if true, all the requests to the Heap API are stubbed to return successfully; this overrides the Faraday-related options

  • faraday_adapter (Symbol) —

    the Faraday adapter used by the Heap API server connection

  • faraday_adapter_args (Array) —

    arguments to the Faraday adapter used by the Heap API server connection



42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/heap/client.rb', line 42

def initialize(options = {})
  @app_id = nil
  @live_connection = nil
  @stubbed_connection = false
  @stubbed = false
  @faraday_adapter = Faraday.default_adapter
  @faraday_adapter_args = []
  @user_agent = "heap-ruby/#{HeapAPI::VERSION} " +
      "faraday/#{Faraday::VERSION} ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"

  options.each do |key, value|
    self.send :"#{key}=", value
  end
end

Instance Attribute Details

#app_id ⇒ String

Returns the Heap application ID from heapanalytics.com/app/install.

Returns:



8
9
10
 
# File 'lib/heap/client.rb', line 8

def app_id
  @app_id
end

#faraday_adapter ⇒ Symbol

Returns the Faraday adapter used by the Heap API server connection.

Returns:

  • (Symbol) —

    the Faraday adapter used by the Heap API server connection

See Also:



16
17
18
 
# File 'lib/heap/client.rb', line 16

def faraday_adapter
  @faraday_adapter
end

#faraday_adapter_args ⇒ Array

Returns arguments to the Faraday adapter used by the Heap API server connection.

Returns:

  • (Array) —

    arguments to the Faraday adapter used by the Heap API server connection



20
21
22
 
# File 'lib/heap/client.rb', line 20

def faraday_adapter_args
  @faraday_adapter_args
end

#stubbed ⇒ Boolean

If true, all the requests to the Heap API are stubbed to return successfully; this overrides the Faraday-related options

Returns:

  • (Boolean) —

    if true, all the requests to the Heap API are stubbed to return successfully; this overrides the Faraday-related options



12
13
14
 
# File 'lib/heap/client.rb', line 12

def stubbed
  @stubbed
end

#user_agent ⇒ String

Returns the User-Agent header value.

Returns:

  • (String) —

    the User-Agent header value



23
24
25
 
# File 'lib/heap/client.rb', line 23

def user_agent
  @user_agent
end

Instance Method Details

#add_user_properties(identity, properties) ⇒ HeapAPI::Client

Assigns custom properties to an existing user.

Parameters:

  • identity (String) —

    an e-mail, handle, or Heap-generated user ID

  • properties (Hash<String, String|Number>) —

    key-value properties associated with the event; each key must have fewer than 1024 characters; each value must be a Number or String with fewer than 1024 characters

Returns:

Raises:

See Also:



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/heap/client.rb', line 83

def add_user_properties(identity, properties)
  ensure_valid_app_id!
  ensure_valid_identity! identity
  ensure_valid_properties! properties

  body = {
    :app_id => @app_id,
    :identity => identity.to_s,
    :properties => properties,
  }
  response = connection.post '/api/add_user_properties', body,
      'User-Agent' => user_agent
  raise HeapAPI::ApiError.new(response) unless response.success?
  self
end

#connection ⇒ Faraday::Connection

The underlying Faraday connection used to make HTTP requests.

Returns:

  • (Faraday::Connection) —

    a Faraday connection object



135
136
137
 
# File 'lib/heap/client.rb', line 135

def connection
  @connection ||= @stubbed ? stubbed_connection : live_connection
end

#new(*args) ⇒ Object

Creates a new client instance.

This is defined here so ‘Heap.new` can be used as a shorthand for `HeapAPI::Client.new`.

See Also:

  • HeapAPI::Client.{HeapAPI{HeapAPI::Client{HeapAPI::Client#initialize}


192
193
194
 
# File 'lib/heap/client.rb', line 192

def new(*args)
  HeapAPI::Client.new(*args)
end

#track(event, identity, properties = nil) ⇒ HeapAPI::Client

Sends a custom event to the Heap API servers.

Parameters:

  • event (String) —

    the name of the server-side event; limited to 1024 characters

  • identity (String) —

    an e-mail, handle, or Heap-generated user ID

  • properties (Hash<String, String|Number>) (defaults to: nil) —

    key-value properties associated with the event; each key must have fewer than 1024 characters; each value must be a Number or String with fewer than 1024 characters

Returns:

Raises:

See Also:



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/heap/client.rb', line 109

def track(event, identity, properties = nil)
  ensure_valid_app_id!

  event_name = event.to_s
  ensure_valid_event_name! event_name
  ensure_valid_identity! identity

  body = {
    :app_id => @app_id,
    :identity => identity.to_s,
    :event => event,
  }
  unless properties.nil?
    body[:properties] = properties
    ensure_valid_properties! properties
  end

  response = connection.post '/api/track', body,
      'User-Agent' => user_agent
  raise HeapAPI::ApiError.new(response) unless response.success?
  self
end