Before we get started, let's make sure you are on the correct guide.
If your store is on Magento 2 or above, then you are on the correct page. Read on!
Table of contents for setting up Magento 2
- Install the Magento 2 Extension
- Set API 'Resource Access' to 'Custom Resources'
- Whitelist Unific IP Addresses
- Authenticate Magento 2 with Unific OAUTH
- Confirm that the integration works
- What to do if you have multiple environments.
Let's get started!
1. Install the Magento 2 Extension
There are two options to install the extension. You only need to follow ONE of options:
Option A: Install using Composer
Option B: Install manually with source code (Only for very advanced users)
Option A: Install using Composer
Do this option only if you are a developer, or send it to your developers:
- SSH to your sever: ssh <user>@<ip-addresss-of-server>
- Go to the public_html directory of the store
- Open composer.json and add below section under repositories:
- Visit https://magento2connector.unific.com
- as the above link says, copy paste the JSON snippet in composer.json
- Save composer.json file
- Next, we need to update composer so that the new changes are picked up by Magento.
Run this command:
- Then we need to tell composer which version to require. The command below will require any version greater than 1.4 of the Unific Connector:
composer require "unific/connector:^1.4.0"
- Now we need to run these two commands to upgrade Magento database schema, and also to clear the cache
- Finally, we need to install cron support for Magento 2. This is required because Unific Connector sends Webhooks in an asynchronous fashion to control the load on Magento 2 installation. The following command will install cron for the www-data user.
sudo -u www-data bin/magento cron:install
Option B: Install manually using the source code
Sometimes store administrators are not allowed to install extensions from Composer OR the Magento Marketplace. In that case we also offer the option to install from the source code. This is not recommended for the novice user!
- Navigate to: https://magento2connector.unific.com/
- On that page, in the "Release" section click the link with the largest release number.
- That will trigger a download. Save that to a location on your computer that you can find. the file name will start with "unific-connector" and end with ".tar"
- Upload this file to the server where Magento 2 store is hosted
- Then navigate to the root folder of your Magento 2 store installation
- Change the "/path/to/connector.tar" portion of the command below to where the tar file was uploaded on that server. Then run the command:
mkdir -p app/code/Unific/Connector && tar -xvf /path/to/connector.tar /app/code/Unific/Connector
If you are having trouble with installation, please contact us at email@example.com.
2. Set API 'Resource Access' to 'Custom Resources' and select resources mentioned below
Log in to the Magento Admin
a. Click on "System" in the main menu
b. Click "Integrations" on the "System" menu
c. Click the pencil icon next to the "Unific-Integration" row
d. Click API
e. Set API 'Resource Access' to 'Custom' and select the 6 Custom Resources as shown in below image (Note: The Unific Reports and Unific Historical resources are available for Unific Connector Versions higher than 1.4.15):
3. Whitelist Unific IP Addresses
If your store has a firewall that may block Unific from connecting to the extension please contact firstname.lastname@example.org and we will send you the necessary ip addresses.
4. Authenticate Magento 2 with Unific OAUTH
All done with the installation? Great! If not, please contact email@example.com.
The next step is to sign up for a Unific account.
- Go to https://app.unific.com/
- Enter the credentials you want
- Fill in the Company Information step
- Next, select Magento 2 as your shopping cart
5. A pop up will appear. If it doesn't appear you might have a popup blocker. Please disable it for app.unific.com.
6. You should already have the Unific extension installed if you are following this guide. If you don't, scroll to the top of this page to see the instructions.
7. Click "Continue" if you already have the Unific extension installed.
8. Next you will see this page where you need to enter certain details.
9. We will have to look inside of Magento 2 admin to find the details this page asks for.
(if you are installing Unific on a non-production environment for testing, see the "What to do if you have multiple environments" section below.)
8. Where to find these details:
Enter the Magento 2 store's URL: This is the production URL of your Magento 2 instance. Use the URL you send to your customers.
The details below are in the Magento 2 admin:
Here's how to find them:
a. Log in to the Magento Admin
b. Click on "System" in the main menu
c. Click "Integrations" on the "System" menu
d. Click the pencil icon next to the "Unific-Integration" row
e. Here you'll find the details you are looking for at the bottom inside of Magento 2
9. Enter the details from Magento and click "Connect"
10. If everything worked well, you should see a "Success" message.
*** If you have multiple environments, you will need to repeat this process for ALL environments ***
11. Continue with the Unific signup process to connect HubSpot (follow the prompts).
5. Confirm that the integration works
The easiest way to confirm that there is a valid connection between Magento 2 and HubSpot is to open up your online store and register a new account.
Unific's extension will send a webhook to Unific and Unific will sync it to HubSpot in a few minutes.
If this is not working, then it may be that Unific is not getting webhooks from Magento 2.
Please contact firstname.lastname@example.org for additional help.
6. What to do if you have multiple environments
It is often the case that there are multiple environments like Dev, QA, Staging, and Production for Magento 2 stores.
If you would like to test Unific on environments other than production you may add multiple stores within a single Unific account and connect them to a single HubSpot portal.
If you do have multiple environments, you must install the extension on all environments that you want to test and go through the "Authenticate Magento 2 with Unific OAUTH " process above.
Error while retrieving integration metadata. Error message: ’java.lang.IllegalStateException: HMAC signing parameters are not present. Integration Id: ‘com.unific.models.integrations.Integration$Id@66fe2c83[organizationId=<organization-id>,integrationId=<integration-id>]‘’.
# If you get the above error while connecting your store to Unific,
There are a few issues that lead to this error:
Check that the access to resources is set to "Custom Resources".
Refer to the section "Set API 'Resource Access' to 'Custom Resources' and select resources mentioned below" above for details.
- If you have a firewall on your store email email@example.com requesting a list of IP addresses to whitelist.
Check that the access token entered is correctly entered (check for whitespaces).
Once these things are done please reconnect your Magento 2 store within Unific
1. Unific's Logging
Unific's log files are put under the directory:
Refer to these log files if the webhooks are not being sent from the extension to Unific.
connector.log - If there are issues during installation, they should be logged here
unific-audit.log - shows the webhooks that are queued up for sending to Unific
2. Problems and Solutions
Error appears in magento.cron.log
Solution: In your MySQL command line, unlock the tables and empty the cron schedule table, with following commands:
Problem B: this error appears in setup.cron.log
- Remove unific connector from composer.json
- Reinstall the Unific Connector extension
Unific Connector extension is updated, but recent changes are not reflected in the Magento 2 Admin on the extension pages.
Solution: Check the opcache.validate_timestamps setting in the PHP configuration of the server:
If enabled, OPcache will check for updated scripts every opcache.revalidate_freq seconds. When this directive is disabled, you must reset OPcache manually via opcache_reset(), opcache_invalidate() or by restarting the Web server for changes to the filesystem to take effect.
If this is set this to false, opcode cache needs to be manually flushed
If the opcode caching setting for php-fpm is set to never expire it will always load old code which is cached until the cache is either manually flushed or php-fpm is restarted
If extension changes are still not immediately reflected after the extension is updated.
Restart PHP-FPM (if your site uses PHP-FPM)
This command might differ based on your operating system
Error while running composer update:
Check if the allow_url_fopen is On or Off using this command on the server (as root user):
If it's 'Off' change allow_url_fopen setting in php.ini file that's being loaded to 'On'.
So it should look like this in php.ini:
Site issues after running composer update:
This request id is actually a log file which will have the actual error in it. That log file will be located in:
If you open that file, it might say:
Run this command on the Magento 2 Server
Reload the site and it should work again.
If you are on an older version of the Unific Connector you may get the error below while running 'composer update':
In this case, you will need to update your composer.json contents to match what is shown in the "Install using Composer" section above.
After making that change, run these commands to remove the older version of the extension and install the newest version.
REST API Calls Unific makes to the Magento 2 Store
Listed are the REST API endpoints from default Magento 2 and the Magento Unific Connector
Connection (Unific Connector):
Method: POST, API Endpoint: /rest/V1/unific/connect
To generate a connection between the Magento store and Unific. It exchanges the Unific Integration Id from Unific for the HMAC from the store. Unific also get the categories, products, customers, and orders count.
Historical Entities Count (Unific Connector):
Method: POST, API Endpoints:
To get the total entities count of each entity so that Unific can anticipate the historical process.
Start Historical full/partial (Unific Connector):
Method: POST, API Endpoints:
To start the historical process to download all/entity-wise existing data from store to Unific.
Method: GET, API Endpoint: /rest/V1/store/storeConfigs
To generate the Product URLs and Image URLs for Products Bought and Abandoned Cart product information.
Method: GET, API Endpoint: /rest/V1/products
To download the missing products (order line items) of order if historical was not done or if the product does not exist with Unific for other reasons.
Generate Sales Rules:
Method: POST, API Endpoint: /rest/V1/salesRules
To create the sales rules in the Magento store the configuration of which will be set in the Unific account's Coupon Generator section.
Generate Coupon Codes:
Method: POST, API Endpoint: /rest/V1/coupons
To generate the coupon codes under the sales rule for each request for coupon code generation.