Module: Instagram::Client::Subscriptions

Included in:
Instagram::Client
Defined in:
lib/instagram/client/subscriptions.rb

Overview

Defines methods related to real-time

Instance Method Summary collapse

Instance Method Details

#create_subscription(options = {}) ⇒ Object #create_subscription(object, callback_url, aspect = "media", options = {}) ⇒ Hashie::Mash

Creates a real-time subscription

Overloads:

  • #create_subscription(options = {}) ⇒ Object

    Parameters:

    • options (Hash) (defaults to: {}) —

      A set of parameters

    Options Hash (options):

    • :object (String) —

      The object you'd like to subscribe to (user, tag, location or geography)

    • :callback_url (String) —

      The subscription callback URL

    • :aspect (String) —

      The aspect of the object you'd like to subscribe to (in this case, "media").

    • :object_id (String, Integer) —

      When specifying a location or tag use the location's ID or tag name respectively

    • :lat (String, Float) —

      The center latitude of an area, used when subscribing to a geography object

    • :lng (String, Float) —

      The center longitude of an area, used when subscribing to a geography object

    • :radius (String, Integer) —

      The distance in meters you'd like to capture around a given point

  • #create_subscription(object, callback_url, aspect = "media", options = {}) ⇒ Hashie::Mash

    Returns The subscription created.

    Examples:

    Creates a new subscription to receive notifications for user media changes.

    Instagram.create_subscription("user", "http://example.com/instagram/callback")

    Parameters:

    • object (String) —

      The object you'd like to subscribe to (user, tag, location or geography)

    • callback_url (String) —

      The subscription callback URL

    • aspect (String) (defaults to: "media") —

      he aspect of the object you'd like to subscribe to (in this case, "media").

    • options (Hash) (defaults to: {}) —

      Addition options and parameters

    Options Hash (options):

    • :object_id (String, Integer) —

      When specifying a location or tag use the location's ID or tag name respectively

    • :lat (String, Float) —

      The center latitude of an area, used when subscribing to a geography object

    • :lng (String, Float) —

      The center longitude of an area, used when subscribing to a geography object

    • :radius (String, Integer) —

      The distance in meters you'd like to capture around a given point

      Note that we only support "media" at this time, but we might support other types of subscriptions in the future.

    Returns:

    • (Hashie::Mash) —

      The subscription created.

See Also:

Supported formats:

  • :json

Requires Authentication:

  • true

    Requires client_secret to be set on the client or passed in options

Rate Limited:

  • true



56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/instagram/client/subscriptions.rb', line 56

def create_subscription(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  object = args.shift
  callback_url = args.shift
  aspect = args.shift
  options.tap {|o|
    o[:object] = object unless object.nil?
    o[:callback_url] = callback_url unless callback_url.nil?
    o[:aspect] = aspect || o[:aspect] || "media"
  }
  response = post("subscriptions", options.merge(:client_secret => client_secret))
  response
end

#delete_subscription(options = {}) ⇒ Object #delete_subscription(subscription_id, options = {}) ⇒ Hashie::Mash

Deletes a real-time subscription

Overloads:

  • #delete_subscription(options = {}) ⇒ Object

    Parameters:

    • options (Hash) (defaults to: {}) —

      Addition options and parameters

    Options Hash (options):

    • :subscription_id (Integer) —

      The subscription's ID

    • :object (String) —

      When specified will remove all subscriptions of this object type, unless an :object_id is also specified (user, tag, location or geography)

    • :object_id (String, Integer) —

      When specifying :object, inlcude an :object_id to only remove subscriptions of that object and object_id

  • #delete_subscription(subscription_id, options = {}) ⇒ Hashie::Mash

    Examples:

    Deletes an application's user change subscription

    Instagram.delete_subscription(:object => "user")

    Parameters:

    • subscription_id (Integer) —

      The subscription's ID

    • options (Hash) (defaults to: {}) —

      Addition options and parameters

    Options Hash (options):

    • :object (String) —

      When specified will remove all subscriptions of this object type, unless an :object_id is also specified (user, tag, location or geography)

    • :object_id (String, Integer) —

      When specifying :object, inlcude an :object_id to only remove subscriptions of that object and object_id

    Returns:

    • (Hashie::Mash)

See Also:

Supported formats:

  • :json

Requires Authentication:

  • true

    Requires client_secret to be set on the client or passed in options

Rate Limited:

  • true



91
92
93
94
95
96
97
 
# File 'lib/instagram/client/subscriptions.rb', line 91

def delete_subscription(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  subscription_id = args.first
  options.merge!(:id => subscription_id) if subscription_id
  response = delete("subscriptions", options.merge(:client_secret => client_secret))
  response
end

#process_subscription(json, &block) ⇒ nil

Process a subscription notification JSON payload

Examples:

Process and handle a notification for a user media change

Instagram.process_subscription(params[:body]) do |handler|

  handler.on_user_changed do |user_id, data|

    user = User.by_instagram_id(user_id)
    @client = Instagram.client(:access_token => _access_token_for_user(user))
    latest_media = @client.user_recent_media[0]
    user.media.create_with_hash(latest_media)
  end

end

Parameters:

  • json (String) —

    The JSON response received by the Instagram real-time server

  • block (Proc) —

    A callable in which callbacks are defined

Returns:

  • (nil)

Raises:

  • (ArgumentError)

See Also:

Supported formats:

  • :json

Requires Authentication:

  • true

    Requires client_secret to be set on the client or passed in options

Rate Limited:

  • true



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/instagram/client/subscriptions.rb', line 124

def process_subscription(json, options={}, &block)
  raise ArgumentError, "callbacks block expected" unless block_given?

  if options[:signature]
    if !client_secret
      raise ArgumentError, "client_secret must be set during configure"
    end
    digest = OpenSSL::Digest::Digest.new('sha1')
    verify_signature = OpenSSL::HMAC.hexdigest(digest, client_secret, json)

    if options[:signature] != verify_signature
      raise Instagram::InvalidSignature, "invalid X-Hub-Signature does not match verify signature against client_secret"
    end
  end

  payload = MultiJson.decode(json)
  @changes = Hash.new { |h,k| h[k] = [] }
  for change in payload
    @changes[change['object']] << change
  end
  block.call(self)
end

#subscriptions(options = {}) ⇒ Hashie::Mash

Returns a list of active real-time subscriptions

Returns The list of subscriptions.

Examples:

Returns a list of subscriptions for the authenticated application

Instagram.subscriptions

Returns:

  • (Hashie::Mash) —

    The list of subscriptions.

See Also:

Supported formats:

  • :json

Requires Authentication:

  • true

    Requires client_secret to be set on the client or passed in options

Rate Limited:

  • true



20
21
22
23
 
# File 'lib/instagram/client/subscriptions.rb', line 20

def subscriptions(options={})
  response = get("subscriptions", options.merge(:client_secret => client_secret))
  response
end