Class: YourMembership::Session

Inherits:
Base
  • Object
show all
Defined in:
lib/your_membership/session.rb

Overview

Note:

It is important to note that the Auth Namespace has been consumed by Sessions in the SDK as sessions and authentication are inextricably linked.

YourMembership Session Object

Session objects encapsulate the creation, storage, authentication, maintenance, and destruction of sessions in the YourMembership.com API.

Sessions can be generic (unauthenticated), authenticated, or abandoned.

  • *Generic sessions* are used extensively whenever the scope of a specific user is not necessary.

  • *Authenticated sessions* are used when the called method requires the scope of a specific user.

  • *Abandoned sessions* are no longer usable and are essentially the same as logging out.

Examples:

Generic (unauthenticated) Session

session = YourMembership::Session.new # => <YourMembership::Session>

Authenticated Session

auth_session = YourMembership::Session.new 'username', 'password' # => <YourMembership::Session>

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from Base

build_XML_request, new_call_id, response_to_array, response_to_array_of_hashes, response_valid?, response_ym_error?

Constructor Details

#initialize(user_name = nil, password = nil) ⇒ Session

Returns a new instance of Session.

Parameters:

  • user_name (String) (defaults to: nil) —

    Constructor takes optional parameters of user_name and password. If supplied then the session will be automatically authenticated upon instantiation.

  • password (String) (defaults to: nil)

See Also:



30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/your_membership/session.rb', line 30

def initialize(user_name = nil, password = nil)
  @call_id = 1
  @user_id = nil

  response = self.class.post('/', :body => self.class.build_XML_request('Session.Create'))

  if self.class.response_valid? response
    @session_id = response['YourMembership_Response']['Session.Create']['SessionID']
  end

  authenticate user_name, password if user_name
end

Instance Attribute Details

#session_id ⇒ String (readonly)

The unique session identifier provided by the API

Returns:

  • (String) —

    the current value of session_id



23
24
25
 
# File 'lib/your_membership/session.rb', line 23

def session_id
  @session_id
end

#user_id ⇒ String, Nil (readonly)

The user id of the user bound to the session, if one exists.

Returns:

  • (String, Nil) —

    the current value of user_id



23
24
25
 
# File 'lib/your_membership/session.rb', line 23

def user_id
  @user_id
end

Instance Method Details

#abandon ⇒ Boolean

Destroys an API session, thus preventing any further calls against it.

Returns:

  • (Boolean) —

    Returns true if the session was alive and successfully abandoned.

See Also:



58
59
60
61
 
# File 'lib/your_membership/session.rb', line 58

def abandon
  response = self.class.post('/', :body => self.class.build_XML_request('Session.Abandon', self))
  self.class.response_valid? response
end

#authenticate(user_name, password) ⇒ Hash

Authenticates a member’s username and password and binds them to the current API session.

Parameters:

  • user_name (String) —

    The username of the member that is being authenticated.

  • password (String) —

    The clear text password of the member that is being authenticated.

Returns:

  • (Hash) —

    Returns the member’s ID and WebsiteID. The returned WebsiteID represents the numeric identifier used by the YourMembership.com application for navigation purposes. It may be used to provide direct navigation to a member’s profile, photo gallery, personal blog, etc.

See Also:



89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/your_membership/session.rb', line 89

def authenticate(user_name, password)
  options = {}
  options[:Username] = user_name
  options[:Password] = password

  response = self.class.post('/', :body => self.class.build_XML_request('Auth.Authenticate', self, options))

  self.class.response_valid? response
  if response['YourMembership_Response']['Auth.Authenticate']
    get_authenticated_user
  else
    false
  end
end

#authenticated? ⇒ Boolean

Indicates whether the session is bound to a user.

Returns:

  • (Boolean) 


133
134
135
136
137
138
139
 
# File 'lib/your_membership/session.rb', line 133

def authenticated?
  if valid?
    !get_authenticated_user.nil?
  else
    false
  end
end

#call_id ⇒ Integer

Returns Auto Increments ad returns the call_id for the session as required by the YourMembership.com API.

Returns:

  • (Integer) —

    Auto Increments ad returns the call_id for the session as required by the YourMembership.com API



44
45
46
 
# File 'lib/your_membership/session.rb', line 44

def call_id
  @call_id += 1
end

#createToken(options = {}) ⇒ Hash

Creates an AuthToken that is bound to the current session. The returned token must be supplied to the Sign-In form during member authentication in order to bind a member to their API session. The sign-in URL, which will include the new AuthToken in its query-string, is returned by this method as GoToUrl. Tokens expire after a short period of time, so it is suggested that the user be immediately redirected the returned GoToUrl after creating an authentication token.

Parameters:

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

Options Hash (options):

  • :RetUrl (String) —

    After authentication the browser will be redirected to this URL

  • :Username (String) —

    The user can optionally be logged in automatically if :Username and :Password are supplied in cleartext.

  • :Password (String) —

    The user’s password

  • :Persist (Boolean) —

    Supplying this value is only necessary when also providing user credentials for automated authentication. The purpose of enabling persistence is to extend an authenticated user’s browsing session beyond its normal inactivity threshold of 20 minutes.

Returns:

  • (Hash) —

    Contains the token String and a URL that will authenticate the session based on that token.

See Also:



122
123
124
125
126
127
128
129
130
 
# File 'lib/your_membership/session.rb', line 122

def createToken(options = {}) # rubocop:disable Style/MethodName
  # Options inlclude: :RetUrl(String), :Username(String),
  # :Password(String), :Persist(Boolean)

  response = self.class.post('/', :body => self.class.build_XML_request('Auth.CreateToken', self, options))

  self.class.response_valid? response
  response['YourMembership_Response']['Auth.CreateToken']
end

#get_authenticated_user ⇒ String, Nil

Get the ID of the currently authenticated user bound to this session.

Returns:

  • (String, Nil) —

    The API ID of the currently authenticated user



143
144
145
 
# File 'lib/your_membership/session.rb', line 143

def get_authenticated_user # rubocop:disable Style/AccessorMethodName
  @user_id = YourMembership::Member.isAuthenticated(self)
end

#ping ⇒ Boolean

When called at intervals of less than 20 minutes, this method acts as an API session keep-alive.

Returns:

  • (Boolean) —

    Returns true if the session is still alive.

See Also:



68
69
70
71
72
 
# File 'lib/your_membership/session.rb', line 68

def ping
  response = self.class.post('/', :body => self.class.build_XML_request('Session.Ping', self))
  self.class.response_valid? response
  response['YourMembership_Response']['Session.Ping'] == '1'
end

#to_s ⇒ String

Returns the session_id

Returns:

  • (String) —

    Returns the session_id



49
50
51
 
# File 'lib/your_membership/session.rb', line 49

def to_s
  @session_id
end

#valid? ⇒ Boolean

Convenience method for ping.

Returns:

  • (Boolean) 


75
76
77
 
# File 'lib/your_membership/session.rb', line 75

def valid?
  ping
end