Cxf Ruby SDK
This is a library to connect apps built on ruby to Cxf.Cloud
Installation
Add gem to the Gemfile
gem 'cxf'
Configure
Add the following configuration to the controller and include MintClients and UserAuthHelper (if you log in with a contact, you can use ContactAuthHelper) NOTE: Proxy automatically renew the token, so you don't need to worry about it
if you haven't run the generator yet, you can use after_action to update the token
require 'cxf'
class ApplicationController < ActionController::Base
include CxfClients
include UserAuthHelper # if you log in with a user
include ContactAuthHelper # if you log in with a contact
after_action :update_user_tokens # if you haven't run the generator yet and you log in with a user
after_action :update_contact_tokens # if you haven't run the generator yet and you log in with a contact
end
Usage
Using Cxf Public API
cxf_pub = Cxf::Pub.new(cxf_url, api_key)
cxf_pub.get_stories
Using Cxf Contact API
cxf_contact_login(email, password)
@cxf_contact.me
Using Cxf User API
cxf_user_login(email, password)
@cxf_user.get_contacts
Using Cxf User API by Service account
# Usually the api_key and the session token are the same, you can go to the service accounts section
# from your Cxf instance and generate your service account api key
cxf_service_account = Cxf::User.new(cxf_url, api_key, api_key)
cxf_service_account.get_contacts
Generate cxf files
This command will generate the cxf_config.yml.erb file, API controlles and routes to have available the cxf endpoints
rails generate cxf_files
Contact tracking usage
Your app controller needs to be inherited from Cxf::BaseController
# application_controller.rb
class ApplicationController < Cxf::BaseController
end
This heritance will make the following class variables available:
| Variable | Description |
|---|---|
| @host | Host defined in cxf_config.yml.erb file |
| @api_key | API key defined in cxf_config.yml.erb file |
| @cxf_pub | An already instanced public client |
| @contact_token | A token used by cxf to identify the contact |
| @visit_id | An identifier of the visit registered |
| @cxf_contact | An already instanced contact client (not usable until call the contact login method) |
And the following controller methods:
| Method | Parameters | Return value | Description |
|---|---|---|---|
| cxf_contact_signed_in? | none | boolean | Indicates if the contact has an active session |
| cxf_contact_login | email, password | void | Starts a contact session |
| cxf_contact_logout | none | void | Ends a contact session |
| cxf_contact_magic_link_login | hash, redirect_in_error | void | Starts a contact session in cxf.cloud and set a session cookie |
Admin controller usage
If want to have a private section where only a cxf user can acces and use the private user api is needed to inherit from the AdminBaseController.
# admin_controller.rb
class AdminController < Cxf::AdminBaseController
end
This heritance will make the following class variables available:
| Variable | Description |
|---|---|
| @host | Host defined in cxf_config.yml.erb file |
| @api_key | API key defined in cxf_config.yml.erb file |
| @cxf_user | An already instanced user client (not usable until call the user login method) |
| @cxf_service_account | An already instanced service_account client |
And the following controller methods:
| Method | Parameters | Return value | Description |
|---|---|---|---|
| cxf_user_login | email, password | void | Starts a user session |
| cxf_user_logout | none | void | Ends a user session |
| cxf_user_signed_in? | none | Boolean | Indicates if the user has an active session |
| cxf_user_magic_link_login | hash | void | Starts a user session in cxf.cloud and set a session cookie |
Cxf config file
The cxf.config.yml file allows to set the Cxf instance to which the implementation will access, it can add the host, api key for Cxf, in addition to setting the cache rules with redis, if you want to add a url to cache , you should add it to the groups array and set the cache time.
# Cxf connection configuration
cxf:
host: http://your_host_goes_here.com
api_key: your_cxf_api_key_goes_here
cxf_slug: slug_id #save id and token in redis
redis_cache:
use_cache: boolean_value_to_enable_and_disable_cache
redis_host: your_redis_server_host
redis_port: your_redis_server_port
redis_db: your_redis_database
groups:
- urls:
- group_of_urls
time: time_that_will_be_applied_to_urls_in_seconds
sdk:
debug: false
# Timeout is specified in seconds
default_http_timeout: 30 # Allows setting a default timeout for all HTTP calls.
get_http_timeout: 30 # Allows setting a default timeout for all GET calls.
post_http_timeout: 30 # Allows setting a default timeout for all POST calls.
put_http_timeout: 30 # Allows setting a default timeout for all PUT calls.
delete_http_timeout: 30 # Allows setting a default timeout for all DELETE calls.
To enable sdk debugging you can change the variable debug. Finally, to configure the sharing of cookies between domains, you can configure the "iframe cookies", where you establish how long the cookie will have, if it is activated and the domains to share cookies (to have this functionality, we recommend the use of the template).
# Cxf connection configuration
sdk:
debug: false
cookies_iframe:
activated: boolean_value_to_enable_and_disable_cookies_iframe
expire_time: expire_time_of_cookies_iframe_in_hours
hosts:
- array_of_host_to_send_cookies
Override default clients
If you want other clients for admin/base controller, you need to specify them with the "define_cxf_clients" method
Example:
# admin_controller.rb
class AdminController < Cxf::AdminBaseController
def define_cxf_clients
%w[contact user pub service_account]
end
end
Override default timeouts
If you want specific timeouts per instance, you can define cxf_sdk_timeouts_config
Example:
# admin_controller.rb
class AdminController < Cxf::AdminBaseController
def cxf_sdk_timeouts_config
{
default: 30,
get: 50,
post: 40,
put: 30,
delete: 10
}
end
end
Error catching
The SDK provides different errors that are identified according to the response provided by Cxf, the errors can be 404, 401, 422, 500, etc. To rescue these errors, it is done as follows:
# Example 1
begin
@cxf_pub.client.raw('/invalid-url')
rescue => Cxf::Errors::ResourceNotFoundException
puts "Error 404"
end
# Example 2
begin
response = @cxf_contact.register(data)
rescue Cxf::Errors::ValidationException => e
response = e.to_h
# This will return a Hash with the information needed to debug
# Example:
{
:client => sdk_instance,
# Client instance
# @host = "https://your_cxf_instance",
# @api_key = current_api_key,
# @session_token = current_session_token,
# @contact_token_id = current_contact_token_id,
# @visit_id = current_visit_id,
# @debug = current_debug_flag,
# @scope = current_scope,
# @base_url = current_base_url
:title => "Request failed with status 422",
:detail => "Unprocessable Entity",
:http_status => 422,
:response => { "email" => ["The email has already been taken."] },
:errors => ["The email has already been taken."]
}
end
The current errors are:
| Error | Status | Full error name |
|---|---|---|
| AccessDeniedException | 401 | Cxf::Errors::AccessDeniedException |
| ResourceNotFoundException | 404 | Cxf::Errors::ResourceNotFoundException |
| MethodNotAllowedException | 405 | Cxf::Errors::MethodNotAllowedException |
| ValidationException | 422 | Cxf::Errors::ValidationException |
| InternalServerException | 500 | Cxf::Errors::InternalServerException |