Mautic rails
RoR helper / wrapper for Mautic API and forms
Rails 4.2.8+, 5.1+ compatible
Installation
Add this line to your application's Gemfile:
gem 'mautic', '~> 2.3'
And then execute:
$ bundle
Also you need migrate database:
$ rails db:migrate
Configuration
add to config/initializers/mautic.rb
:
Mautic.configure do |config|
# This is for oauth handshake token url. I need to know where your app listen
config.base_url = "https://my-rails-app.com"
# OR it can be Proc
# *optional* This is your default mautic URL - used in form helper
config.mautic_url = "https://mautic.my.app"
# Set authorize condition for manage Mautic::Connections
config. = ->(controller) { false }
end
Manage mautic connections
You can use builtin Mautic:ConnectionsController:
add to config/routes.rb
mount Mautic::Engine => "/mautic"
note: Make sure that you have some user authorization. There is builtin mechanism, in Mautic.config.authorize_mautic_connections
= which return false
to prevent all access by default (see: app/controllers/mautic/connections_controller.rb:3). For change this, you need add to config/initializers/mautic.rb
:
Mautic.config. = ->(controller) { current_user.admin? }
OR use your own controller, by including concern
class MyOwnController < ApplicationController
before_action :authorize_user
include Mautic::ConnectionsControllerConcern
end
Concern require additional routes (authorize and oauth2) in routes.rb
resources :my_resources do
member do
get :authorize
get :oauth2
end
end
Create mautic connection
- In your mautic, create new
- Got to
/your-mount-point/connections
- Create new connection - enter URL to your mautic
Copy
callback url
then go to you mauticIn mautic you need add API oauth2 login.
http://localhost:3000/mautic/connections/:ID/oauth2
ID = is your Mautic::Connection ID
Create new Oauth2 API connections. Use
callback url
from previous step and copykey
andsecret
to form in your appUpdate and use
Authorize
button for handshake
For example of integration check https://github.com/luk4s/redmine_mautic
Usage
Find connection which you want to use:
m = Mautic::Connection.last
Get specify contact:
contact = m.contact.find(1) # => #<Mautic::Contact id=1 ...>
Collections of contacts:
m.contacts.where("gmail").each do |contact|
#<Mautic::Contact id=12 ...>
#<Mautic::Contact id=21 ...>
#<Mautic::Contact id=99 ...>
end
New instance of contacts:
contact = m.contacts.new({ email: "[email protected]"} )
contact.save # => true
Update contact
contact.email = ""
contact.save # => false
contact.errors # => [{"code"=>400, "message"=>"email: This field is required.", "details"=>{"email"=>["This field is required."]}}]
Do not contact
contact.do_not_contact? # => false
contact.do_not_contact! message: "Some reason"
contact.do_not_contact? # => true
Remove do not contact
contact.do_not_contact? # => true
contact.remove_do_not_contact!
contact.do_not_contact? # => false
Of course you can use more than contact: assets
, emails
, companies
, forms
, points
...
Gem provides simple Mautic form submit
There are two options of usage:
- Use default mautic url from configuration and shortcut class method:
ruby # form: ID of form in Mautic *required* # url: Mautic URL - default is from configuration # request: request object (for domain, and forward IP...) *optional* Mautic::FormHelper.submit(form: "mautic form ID") do |i| i.form_field1 = "value1" i.form_field2 = "value2" end
- Or create instance
ruby # request is *optional* m = Mautic::FormHelper.new("https://mymautic.com", request) m.data = {} # hash of attributes m.push # push data to mautic
Webhook receiver
Receive webhook from mautic, parse it and prepare for use.
add concern to your controller
include Mautic::ReceiveWebHooks
in routes must be specify
:mautic_id
, for example:post "webhook/:mautic_id", action: "webhook", on: :collection
Contributing
Ideas and pull requests are welcome!
License
The gem is available as open source under the terms of the MIT License.