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.create # => <YourMembership::Session>

Authenticated Session

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

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

Constructor Details

#initialize(session_id = nil, call_id = 1, user_id = nil) ⇒ Session

Generates an empty session



27
28
29
30
31
 
# File 'lib/your_membership/session.rb', line 27

def initialize(session_id = nil, call_id = 1, user_id = nil)
  @session_id = session_id
  @call_id = call_id
  @user_id = user_id
end

Instance Attribute Details

#call_id ⇒ Integer (readonly)

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



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

def call_id
  @call_id
end

#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

Class Method Details

.create(user_name = nil, password = nil) ⇒ Object

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:



37
38
39
40
41
42
43
44
45
46
 
# File 'lib/your_membership/session.rb', line 37

def self.create(user_name = nil, password = nil)
  response = post('/', :body => build_XML_request('Session.Create'))

  if response_valid? response
    session = new response['YourMembership_Response']['Session.Create']['SessionID']
  end

  session.authenticate user_name, password if user_name
  session
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:



63
64
65
66
 
# File 'lib/your_membership/session.rb', line 63

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:



94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/your_membership/session.rb', line 94

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) 


138
139
140
 
# File 'lib/your_membership/session.rb', line 138

def authenticated?
  valid? && !get_authenticated_user.nil?
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:



127
128
129
130
131
132
133
134
135
 
# File 'lib/your_membership/session.rb', line 127

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



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

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:



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

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



54
55
56
 
# File 'lib/your_membership/session.rb', line 54

def to_s
  @session_id
end

#valid? ⇒ Boolean

Convenience method for ping.

Returns:

  • (Boolean) 


80
81
82
 
# File 'lib/your_membership/session.rb', line 80

def valid?
  ping
end