class AY

Provides access to the Collins Frontend Platform. All the public methods cover a single API query.

author: Collins GmbH & Co KG

Constants

API_ENVIRONMENT_LIVE: environment-named for api-live
API_ENVIRONMENT_SANDBOX: environment-named for api-sandbox
API_ENVIRONMENT_STAGE: environment-named for api-staging
IMAGE_URL_LIVE: url for live
IMAGE_URL_SANDBOX: url for the sandbox
IMAGE_URL_STAGE: url for staging

Attributes

about_you_client[RW]

the client which performs the api calls

api_endpoint[RW]

the endpoint used for api calls

app_id[RW]

the app id of the app which should be represented by an instance of AY

app_password[RW]

the authentication token from dev-center for the app id

base_image_url[RW]

the url for getting images

cache[RW]

the CacheServer

environment[RW]

the environment which should be used by the app

logger[RW]

a logger template

model_factory_instance[RW]

the model factory builds model objects based on the api response

session_id[RW]

the session id from a user using this app

Public Class Methods

new( app_id, app_password, session_id = 'SESSION_ID', cache = nil, api_endpoint = API_ENVIRONMENT_LIVE, result_factory = nil, logger = nil ) click to toggle source

the Constructor for the AY class

Args :
- app_id -> The App-Id of the App
- app_password -> The Auth-Token of the App
- session_id -> A String containing the sessionId of the User
- api_endpoint -> Can be either live or staging
- resultFactory -> If nil it will use the DefaultModelFactory with the DefaultFacetManager
- logger -> Logger-Template
- cache -> The preferred Caching-Strategy
Returns :
- Instance of AY

# File lib/aboutyou-sdk.rb, line 63
def initialize(
    app_id,
    app_password,
    session_id = 'SESSION_ID',
    cache = nil,
    api_endpoint = API_ENVIRONMENT_LIVE,
    result_factory = nil,
    logger = nil
  )

  self.session_id   = session_id
  self.app_id       = app_id
  self.app_password = app_password
  self.about_you_client = AboutYou::SDK::Client.new(
    app_id,
    app_password,
    api_endpoint,
    logger
  )

  self.cache = cache
  if result_factory
    self.model_factory_instance = result_factory
  else
    init_default_factory(self.cache)
  end

  if api_endpoint == API_ENVIRONMENT_STAGE
    self.base_image_url = (IMAGE_URL_STAGE)
    self.environment = API_ENVIRONMENT_STAGE
  elsif api_endpoint == API_ENVIRONMENT_SANDBOX
    self.base_image_url = (IMAGE_URL_SANDBOX)
    self.environment = API_ENVIRONMENT_SANDBOX
  elsif api_endpoint == API_ENVIRONMENT_LIVE
    self.base_image_url = (IMAGE_URL_LIVE)
    self.environment = API_ENVIRONMENT_LIVE
  end
end

Public Instance Methods

add_item_to_basket(session_id, variant_id, amount = 1) click to toggle source

Adds a single item into the basket. You can specify an amount. Please mind, that an amount > 1 will result in amount basket positions. So if you read out the basket again later, it’s your job to merge the positions again.

Args :
- session_id -> A String containing the sessionId of the User
- variant_id -> Id of the Variant which should be added to the basket
- amount -> The Amount of the Item which should be added to the basket
Fails :
- if the variant id cant be transformed into an Integer
Returns :
- Instance of AboutYou::SDK::Model::Basket

# File lib/aboutyou-sdk.rb, line 120
def add_item_to_basket(session_id, variant_id, amount = 1)
  basket = AboutYou::SDK::Model::Basket.new

  unless variant_id.is_a?(Integer)
    if variant_id.is_a?(String) && variant_id[/\d/]
      variant_id = Integer(variant_id)
    else
      fail 'the variant id must be an integer or string with digits'
    end
  end

  amount.times do
    basket.update_item(AboutYou::SDK::Model::Basket::BasketItem.new(
        generate_basket_item_id,
        variant_id
    ))
  end

  update_basket(session_id, basket)
end

api_endpoint=(api_endpoint) click to toggle source

Setter-Method for the api endpoint

Args :
- api_endpoint -> the endpoint can be the string ‘stage’ or ‘live’, then the default endpoints will be used or an absolute url

# File lib/aboutyou-sdk.rb, line 562
def api_endpoint=(api_endpoint)
  about_you_client.api_endpoint = api_endpoint
end

app_credentials=(app_id, app_password) click to toggle source

Setter-Method for the app-Credentials

Args :
- app_id -> the id of an app
- app_password -> the auth-token for the app

# File lib/aboutyou-sdk.rb, line 549
def app_credentials=(app_id, app_password)
  self.app_id                   = app_id
  self.app_password             = app_password
  about_you_client.app_id       = app_id
  about_you_client.app_password = app_password
end

base_image_url=(base_image_url = nil) click to toggle source

Setter-Method for the base image url

Args :
- base_image_url -> nil will reset to the default url, false to get relative urls, otherwise the url prefix

# File lib/aboutyou-sdk.rb, line 572
def base_image_url=(base_image_url = nil)
  if !base_image_url
    @base_image_url = IMAGE_URL_LIVE
  elsif base_image_url.is_a?(String)
    @base_image_url = base_image_url.gsub(/[#{'/'}]+$/, '')
  else
    @base_image_url = ''
  end

  model_factory.base_image_url = @base_image_url
end

category_manager(fetch_if_empty = true) click to toggle source

The Categories will be fetched automatically, if required by any other fetch method

Args :
- fetchIfEmpty -> defines whether to fetch if empty or not [optional]
Returns :
- Instance of AboutYou::SDK::CategoryManager::DefaultCategoryManager

# File lib/aboutyou-sdk.rb, line 311
def category_manager(fetch_if_empty = true)
  category_manager = model_factory.category_manager

  if fetch_if_empty && category_manager.empty?
    query.require_category_tree.execute_single
  end

  category_manager
end

fetch_autocomplete( searchword, limit = 50, types = [ AboutYou::SDK::Model::Autocomplete::TYPE_PRODUCTS, AboutYou::SDK::Model::Autocomplete::TYPE_CATEGORIES ] ) click to toggle source

Returns the result of an auto completion API request. Auto completion searches for products and categories by a given prefix (searchword).

Args :
- searchword -> The prefix search word to search for
- limit -> Maximum number of results [optional]
- types -> Array of types to search for [optional]
Returns :
- Instance of AboutYou::SDK::Model::Automcomplete

# File lib/aboutyou-sdk.rb, line 218
def fetch_autocomplete(
  searchword,
  limit = 50,
  types = [
    AboutYou::SDK::Model::Autocomplete::TYPE_PRODUCTS,
    AboutYou::SDK::Model::Autocomplete::TYPE_CATEGORIES
  ]
)
  query.fetch_autocomplete(searchword, limit, types).execute_single
end

fetch_basket(session_id) click to toggle source

Fetch the basket of the given session_id.

Args :
- session_id -> A String containing the sessionId of the User
Returns :
- Instance of AboutYou::SDK::Model::Basket

# File lib/aboutyou-sdk.rb, line 270
def fetch_basket(session_id)
  query.fetch_basket(session_id).execute_single
end

fetch_categories_by_ids(ids = nil) click to toggle source

Returns the result of a category search API request. By passing one or several category ids it will return a result of the categories data.

Args :
- ids -> either a single category ID as integer or an array of IDs [optional]
Returns :
- Instance of AboutYou::SDK::Model::CategoriesResult

# File lib/aboutyou-sdk.rb, line 285
def fetch_categories_by_ids(ids = nil)
  # we allow to pass a single ID instead of an array
  ids = Array(ids) if ids

  AboutYou::SDK::Model::CategoriesResult.new(category_manager, ids)
end

fetch_category_tree() click to toggle source

Fetches the Root Categories of the Category Tree

Returns :
- Instance of AboutYou::SDK::Model::CategoryTree

# File lib/aboutyou-sdk.rb, line 298
def fetch_category_tree
  AboutYou::SDK::Model::CategoryTree.new(category_manager)
end

fetch_child_apps() click to toggle source

Returns the list of child apps

returns :
- an Array containing all child Apps

# File lib/aboutyou-sdk.rb, line 473
def fetch_child_apps
  query.fetch_child_apps.execute_single
end

fetch_facet(params) click to toggle source

Fetch single facets by id and group id

Args :
- params -> Hash containing 2 keys: “id”, “group_id”
Returns :
- AboutYou::SDK::Model::Facet

# File lib/aboutyou-sdk.rb, line 448
def fetch_facet(params)
  query.fetch_facet(params).execute_single
end

fetch_facet_types() click to toggle source

Fetches all possible Facet types

Returns :
- Array with all group ids

# File lib/aboutyou-sdk.rb, line 422
def fetch_facet_types
  query.fetch_facet_types.execute_single
end

fetch_facets(group_ids = []) click to toggle source

Fetch the facets of the given group_ids

Args :
- group_ids -> Array of group ids [optional]
Returns :
- Instance of AboutYou::SDK::Model::Facet

# File lib/aboutyou-sdk.rb, line 409
def fetch_facets(group_ids = [])
  if model_factory_instance.facet_manager.empty?
    query.fetch_facets.execute_single
  end
  model_factory_instance.facet_manager.facets_by_group_ids(group_ids)
end

fetch_order(order_id) click to toggle source

fetches Order for specific id

Args :
- orderId -> The id for which an order should be returned
Returns :
- Instance of AboutYou::SDK::Model::Order

# File lib/aboutyou-sdk.rb, line 435
def fetch_order(order_id)
  query.fetch_order(order_id).execute_single
end

fetch_product_search(criteria) click to toggle source

Fetches the response for a product search

Args :
- criteria -> Hash containing one or multiple search terms
Returns :
- Instance of AboutYou::SDK::Model::ProductSearchResult

# File lib/aboutyou-sdk.rb, line 396
def fetch_product_search(criteria)
  query.fetch_product_search(criteria).execute_single
end

fetch_products_by_eans(eans, fields = []) click to toggle source

Fetches products for specific eans

Args :
- eans -> Either a single ean or an Array of eans which should be fetched
- fields -> Additional product fields which should be fetched for each product [optional]
Returns :
- Instance of AboutYou::SDK::Model::ProductsEanResult

# File lib/aboutyou-sdk.rb, line 380
def fetch_products_by_eans(eans, fields = [])
  # we allow to pass a single ID instead of an array
  eans = Array(eans)

  query.fetch_products_by_eans(eans, fields).execute_single
end

fetch_products_by_ids(ids, fields = []) click to toggle source

Fetches the products for specific ids

Args :
- ids -> Either a single id or an Array of ids which should be fetched
- fields -> Additional product fields which should be fetched for each product [optional]
Returns :
- Instance of AboutYou::SDK::Model::ProductsResult

# File lib/aboutyou-sdk.rb, line 331
def fetch_products_by_ids(ids, fields = [])
  # we allow to pass a single ID instead of an array
  ids = Array(ids)
  result = query.fetch_products_by_ids(ids, fields).execute_single
  products_not_found = result.ids_not_found

  if !products_not_found.empty? && logger
    logger.warning('products not found: appid=' + app_id +
        ' product ids=[' + products_not_found.join(',') + ']'
    )
  end

  result
end

fetch_spell_correction(searchword, category_ids = nil) click to toggle source

Returns the result of an spell correction API request. spell correction searches for products by a given searchword. You might filter by category ids aswell.

Args :
- searchword -> The prefix search word to search for
- category_ids -> The category ids used as a filter [optional]
Fails :
- if a category id cant be transformed into an Integer
- if a category id is smaller then 1
Returns :
- Array of Strings

# File lib/aboutyou-sdk.rb, line 245
def fetch_spell_correction(searchword, category_ids = nil)
  unless category_ids.nil?
    # we allow to pass a single ID instead of an array
    category_ids = Array(category_ids)

    category_ids.each do |cat_id|
      fail 'InvalidArgumentException! A single category ID must be an integer
        or a numeric string' unless cat_id.is_a?(Integer) || cat_id[/\d/]
      fail '\InvalidArgumentException! A single category ID must be greater
        than 0' if cat_id < 1
    end
  end

  query.fetch_spell_correction(searchword, category_ids).execute_single
end

fetch_suggest(searchword) click to toggle source

Returns the result of a suggest API request. Suggestions are words that are often searched together with the searchword you pass (e.g. “stretch” for “jeans”).

Args :
- searchword -> The search string to search for
Returns :
- an Array containing the suggestions

# File lib/aboutyou-sdk.rb, line 463
def fetch_suggest(searchword)
  query.fetch_suggest(searchword).execute_single
end

fetch_variants_by_ids(ids) click to toggle source

Fetches variants for specific ids

Args :
- ids -> Either a single id or an Array of ids which should be fetched
Returns :
- Instance of AboutYou::SDK::Model::VariantsResult

# File lib/aboutyou-sdk.rb, line 355
def fetch_variants_by_ids(ids)
  # we allow to pass a single ID instead of an array
  ids = Array(ids)
  result = query.fetch_live_variant_by_ids(ids).execute_single
  variants_not_found = result.variants_not_found

  if result.variants_not_found? && logger
    logger.warning('variants or products for variants not found: appid=' +
        app_id + ' variant ids=[' + variants_not_found.join(',') + ']'
    )
  end

  result
end

generate_basket_item_id() click to toggle source

Method to create a unique item id for items in basket

Args :
Returns :
- an Intger

# File lib/aboutyou-sdk.rb, line 149
def generate_basket_item_id
  'i_' + SecureRandom.uuid
end

init_default_factory(cache = nil) click to toggle source

initializes the default model factory

Args :
- cache -> an Instance of the used cache [optional]

# File lib/aboutyou-sdk.rb, line 590
def init_default_factory(cache = nil)
  self.model_factory_instance = AboutYou::SDK::Factory::DefaultModelFactory.new(self)

  model_factory_instance.initialize_managers(
    AboutYou::SDK::Model::FacetManager::DefaultFacetManager.new(
      cache,
      app_id,
      self
    ),
    AboutYou::SDK::Model::CategoryManager::DefaultCategoryManager.new(
      cache,
      app_id,
      self
    )
  )
  model_factory_instance.base_image_url = base_image_url
end

initiate_order(session_id, success_url, cancel_url = nil, error_url = nil) click to toggle source

Method to initiaite the order

Args :
- session_id -> A String containing the sessionId of the User
- successUrl -> callback URL if the order was OK
- cancelUrl -> callback URL if the order was canceled [optional]
- errorUrl -> callback URL if the order had any exceptions [optional]
Returns :
- Instance of AboutYou::SDK::Model::InitiateOrder

# File lib/aboutyou-sdk.rb, line 196
def initiate_order(session_id, success_url, cancel_url = nil, error_url = nil)
  query.initiate_order(
    session_id,
    success_url,
    cancel_url,
    error_url
  ).execute_single
end

java_script_tag() click to toggle source

Returns a HTML script tag that loads the Collins JavaScript fie.

Returns :
- a string containing an HTML script tag

# File lib/aboutyou-sdk.rb, line 538
def java_script_tag
  '<script type="text/javascript" src="' + java_script_url + '"></script>'
end

java_script_url() click to toggle source

Returns the URL to the Collins JavaScript file for helper functions to add product variants into the basket of ABOUT YOU or auto-resizing the iframe. This URL may be changed in future, so please use this method instead of a hard coded URL into your HTML template.

Returns :
- a string containing an url to the javascript file

# File lib/aboutyou-sdk.rb, line 523
def java_script_url
  if environment == API_ENVIRONMENT_STAGE
    '//devcenter-staging-www1.pub.collins.kg:81/appjs/' +
      String(app_id) + '.js'
  else
    '//developer.aboutyou.de/appjs/' + String(app_id) + '.js'
  end
end

model_factory() click to toggle source

Method for getting the model factory. If no model factory is set it initializes the default one

Returns :
- an Instance of AboutYou::SDK::Factory::DefaultModelFactory

# File lib/aboutyou-sdk.rb, line 493
def model_factory
  init_default_factory unless model_factory_instance

  model_factory_instance
end

product_search_criteria(session_id = nil) click to toggle source

Method for getting the product search criteria base class, on which you can specify your criteria

Args :
- session_id -> a string containing the session id [optional]
Returns :
- AboutYou::SDK::Criteria::ProductSearchCriteria

# File lib/aboutyou-sdk.rb, line 508
def product_search_criteria(session_id = nil)
  session_id  = self.session_id unless session_id

  AboutYou::SDK::Criteria::ProductSearchCriteria.new(session_id)
end

query() click to toggle source

Method for getting the query

Returns :
- an Instance of AboutYou::SDK::Query

# File lib/aboutyou-sdk.rb, line 483
def query
  AboutYou::SDK::Query.new(about_you_client, model_factory)
end

remove_items_from_basket(session_id, item_ids) click to toggle source

Method to remove items from basket

Args :
- session_id -> A String containing the sessionId of the User
- itemIds -> an Array of Item ids which should be removed
Returns :
- Instance of AboutYou::SDK::Model::Basket

# File lib/aboutyou-sdk.rb, line 163
def remove_items_from_basket(session_id, item_ids)
  basket = AboutYou::SDK::Model::Basket.new
  basket.delete_items(item_ids)

  update_basket(session_id, basket)
end

update_basket(session_id, basket) click to toggle source

Method to update a given basket

Args :
- session_id -> A String containing the sessionId of the User
- basket -> an Instance of a basket
Returns :
- Instance of AboutYou::SDK::Model::Basket

# File lib/aboutyou-sdk.rb, line 180
def update_basket(session_id, basket)
  query.update_basket(session_id, basket).execute_single
end