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

  • 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


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

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_idString

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_adapterSymbol

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_argsArray

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

#stubbedBoolean

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_agentString

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

Assign 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:


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

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

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

#connectionFaraday::Connection

The underlying Faraday connection used to make HTTP requests.

Returns:

  • (Faraday::Connection)

    a Faraday connection object


132
133
134
# File 'lib/heap/client.rb', line 132

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}

189
190
191
# File 'lib/heap/client.rb', line 189

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:


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

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

  event_name = event.to_s
  ensure_valid_event_name! event_name

  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