AppManager
Welcome to the new gem of Hulkapps.com ! An API wrapper of Hulkapps.com's AppManager portal.
Installation
- Add following line to your application's Gemfile:
gem 'app_manager'
- Execute following in terminal:
bundle install
rails g app_manager:install
this install command will mount routes in your rails route and will create a config file at config/initializers/app_manager.rb
rails db:migrate
Configuration
Set Shopify API version to 2022-04 as app_manager is best compatible with this version.
Please map new fields (which added by app manager migration) in 'config.field_names' in below initializer file which is generated by install command. Please note: this is important step.
Please update blank fields in initializer file. Please copy 'uuid' from this file and paste in the following file and make sure that is unique per feature. After copying put your 'app name' next to 'uuid' column in this file.
AppManager.configure do |config|
config.enable_caching = false # Optional, True to enable app-manager api response caching, default is enabled from gem
config.expires_in = 1.days # Optional, Example: 30.seconds, 5.minutes or 2.days Default caching is for 1.days from gem
config.app_url = '' # App URL like https://volumediscount.hulkapps.dev/ or #https://5044-2409-4052-209a-69da-9d7-925a-9418-a9c3.ngrok.io
config.shopify_api_key = '' # Shopify api key of app
config.shopify_api_version = '' # Must be 2022-04 or latest
config.shopify_table_name = 'shops' # Table name which is generated by shopify mostly it is 'shops'
config.shopify_domain_field = 'shopify_domain' #shopify domain field
config.plan_id_or_name_field = 'plan_id'
config.shopify_app_slug = '' #Add your app slug here
config.plan_page_route = '' #Add your app's plan page route here without first slash. Ex. "payment"
config.field_names = {
'name' => 'shopify_domain', # demo-rahul-tiwari.myshopify.com
'shopify_email' => 'email', # [email protected]
'shopify_token' => 'shopify_token',
'shopify_plan' => 'shopify_plan', # partner_test
'plan_id' => 'plan_id', # 1. t
'created_at' => 'created_at', # 2022-04-15 10:43:05
'trial_activated_at' => 'trial_activated_at', # field name that stores trial start/activated date
'grandfathered' => 'grandfathered',
'total_trial_days' => '' #optional, put a trial days field from your shops table otherwise leave it blank
}
config.plan_features = [
{
"uuid" => "b48a3a6c-c1fb-11ec-9d64-0242ac120002",
"name" => "Features 1",
"slug" => "feature-1",
"description" => "Feature Description",
"value_type" => "integer",
"format" => "count",
"display_order" => 1,
"hidden_feature" => false,
"group_order" => "1",
"group" => "Group Name",
},
{
"uuid" => "9f18f95a-bfaf-11ec-9d64-0242ac120002",
"name" => "Features 2",
"slug" => "feature-2",
"description" => "Feature Description",
"value_type" => "boolean",
"format" => "percentage",
"display_order" => 2,
"hidden_feature" => false,
"group_order" => "1",
"group" => "Group Name",
},
{
"uuid" => "9f190a26-bfaf-11ec-9d64-0242ac120002",
"name" => "Features 3",
"slug" => "feature-3",
"description" => "Feature Description",
"value_type" => "string",
"format" => "string",
"display_order" => 3,
"hidden_feature" => false,
"group_order" => "1",
"group" => "Group Name",
},
{
"uuid" => "9f191340-bfaf-11ec-9d64-0242ac12000",
"name" => "Features 4",
"slug" => "feature-4",
"description" => "Feature Description",
"value_type" => "array",
"values" => [
"val-1" => "val 1",
"val-2" => "val 2",
"val-3" => "val 3",
],
"format" => "string",
"display_order" => 4,
"hidden_feature" => false,
"group_order" => "1",
"group" => "Group Name",
}
]
end
#Required, Values type : integer, boolean, string, array #
#Format: percentage, count, string
- You must have to set ENV variable with key 'APP_MANAGER_ACCESS_TOKEN' in your application.yml or .env file like this:
APP_MANAGER_ACCESS_TOKEN: 'XXXXXXXXXXXXXXXXXXX'
APP_MANAGER_API_URL: 'https://XXXXXXXX.com'
- App Manager provides a rake task that must needs to include in your existing app cron for every 10 minutes. Like if you are using whenever gem then you MUST need to include following rake take in your 'schedule.rb' (created by whenever gem)
every 10.minutes do
rake 'sync:local_app_manager'
end
Usage
- App Manager provides a helper module which needs to include in your 'shop' model something like below
class Shop < ActiveRecord::Base
include AppManager::Model
end
and then you can use follwing methods with your shop objects.
@shop.has_plan # return true or false
@shop.plan_features # return array of plan features of your shop's plan
@shop.has_feature('feature-1') # provide slug of feature which you set in your 'config.plan_features' in config/initializers/app_manager.rb
#return true/false
@shop.get_feature('feature-3') # provide slug of feature and this returns value of feature which is set in portal.
@shop.get_remaining_days # return integer based on trial activated date.
@shop.get_plan # return current plan hash
if you pass @shop.get_plan(plan_id) it will return that particular plan hash like @shop.get_plan(311)
@shop.get_charge # return current charge hash from app manager with 'active_charge' & 'cancelled_charge' keys, it will return nil if current plan is free
@shop.cancel_charge # it will cancel charge in app manager and will return success to true if done from app manager
@shop.set_default_plan(plan_id=nil) #if plan id is passed nil, then it will set the free(public and $0 price) plan_id in database and if passed it will set that plan_id in database.
@shop.get_plans_by_features(feature_slugs) # pass feature_slugs as an array even if one slug and it will return plans array which have that slug found. Example:
@shop.get_plans_by_features(['quantity-based-discount'])
@shop.get_plans_by_features(['quantity-based-discount','multiple-discount-types'])
you can pass string argument 'exclude_current_plan' which will return all plans that matching features except current plan
@shop.get_plans_by_features(['quantity-based-discount'],'exclude_current_plan')
@shop.get_plans_by_features(['quantity-based-discount','multiple-discount-types'],'exclude_current_plan')
@shop.get_all_plans # return all app plans array
@shop.get_active_charge_app_manager # return active charge hash from app manager otherwise nil
@shop.update_app_manager_charge # return true if shop has shopify recurring charge but app manager doesn't then it update to app manager and return true otherwise nil. This method also accepts current shopify charge id, so you can pass it if you already. This will reduce the extra call like this @shop.update_app_manager_charge("xx23432434")
@shop.update_app_manager_charge_with_plan_id # same as update_app_manager_charge method, the only difference is that, it will not check the plan_id in the shop table is valid from app manager. This method also accepts two parameters, first is current shopify charge id and second is plan_id .It shop table doesn't have plan_id saved then you can pass in second parameter. @shop.update_app_manager_charge_with_plan_id("xx23432434",23)
@shop.get_current_shopify_charge # return active charge hash from shopify https://shopify.dev/docs/api/admin-graphql/2022-10/queries/currentAppInstallation otherwise nil
@shop.active_shopify_charge_id # return active shopify charge id if shop has any current shopify reccurring charge otherwise nil
@shop.cancel_current_shopify_charge # It will cancel charge in shopify if there is any, if success then it will cancel charge in app manager as well using (@shop.cancel_charge ) and will make plan_id and grandfathered field to false. It will clear cache as well.
@shop.active_shopfiy_charge_full #It will give shopify recurring charge graphql object with discounted price details
@shop.usage_charge_call(amount,description,shopify_charge_id #optional) #It will call usage charge API. Amount parameter must be present and should be float value. You can skip shopify_charge_id if you want to pass active shopify charge id. This method will automatically pull that, otherwise you can pass it. You have to pass descriptions as a second parameter.
Discount Link Integration
Update app manager vue package in Rails+Vue apps & for for non-vue apps, update css or js from npm package, minimum version should be 2.4.4
Update app manager gem in your project's Gemfile
gem 'app_manager', '2.2.3'
- In Rails project, in application.rb, add following line after require "rails/all" line
require 'app_manager/set_local_storage'
- In route.rb file, add following route with constraints
ruby condition = ->(request) { request.path_info.include?('/discount/') } plan_url = "https://admin.shopify.com/admin/apps/#{ENV['SHOPIFY_APP_SLUG']}/home/plan" constraints(condition) do get '/discount/*any', to: AppManager::SetLocalStorage.new(Rails.application, condition, plan_url) end - If updating gem from 1.6.1, then run these commands on rails root.
Note: In this command, Please do not overwrite app_manager.rb file so press n
rails g app_manager:install
This will add a new migration file in your db/app_manager directory
rails db:migrate
Extras
- To view the app_manager ruby gem is working in your rails app you can use rails console and initialize app_manager instance like with App Manager Portal access:
ob = AppManager::Client.new(ENV['APP_MANAGER_ACCESS_TOKEN'])
To get banners use this command:
ob.
- For Vue UI Library in Rails Project:
Please make sure you have following line in your route file otherwise add this manually.
mount AppManager::Engine, at: "/"
Development
After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/app_manager. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
Code of Conduct
Everyone interacting in the AppManager project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.