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 (max 5000 meters)

  • #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 (max 5000 meters)

      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:

Rate Limited:

  • true

Supported formats:

  • :json

Requires Authentication:

  • true

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



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

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["data"]
end

#delete_subscription(options = {}) ⇒ Object #delete_subscription(subscription_id, options = {}) ⇒ nil

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 = {}) ⇒ nil

    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:

    • (nil)

See Also:

Rate Limited:

  • true

Supported formats:

  • :json

Requires Authentication:

  • true

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



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

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["data"]
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:

Rate Limited:

  • true

Supported formats:

  • :json

Requires Authentication:

  • true

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



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

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
    verify_signature = HMAC::SHA1.hexdigest(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:

Rate Limited:

  • true

Supported formats:

  • :json

Requires Authentication:

  • true

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



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

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