communify

Communify

Communify is a powerful Ruby gem that enables your backend to seamlessly send SMS through Twilio, push notifications via Firebase Cloud Messaging, and maintain detailed logs of all communications. It also integrates email tracking for messages sent through ActionMailer.

Why Choose Communify?

Effective communication is crucial for businesses to engage with their customers about app features, updates, and important information. Communify provides a streamlined solution for integrating SMS, push notifications, and email logging into your Rails application, allowing developers to implement all three communication channels with minimal code.

By simplifying the coding process, Communify enables you to focus on enhancing user experience and fostering strong customer relationships.

Features

• SMS Integration: Easily send SMS messages through Twilio.
• Push Notifications: Send real-time notifications via Firebase Cloud Messaging.
• Email Logging: Track all emails sent via ActionMailer.
• Comprehensive Logging: Maintain logs for all communications, enhancing tracking and auditing capabilities.

Installation

To integrate Communify into your Rails application, add the following line to your Gemfile:

gem 'communify'

Then, run the following command to install:

bundle install

Alternatively, you can install it directly using:

gem install communify

Note: By installing Communify, you automatically include the twilio-ruby gem (version ~> 5.69.0) and the fcmpush gem (version ~> 1.4.4). Communify abstracts the functionality of these gems, streamlining their integration and usage in your application.

Requirements

To ensure the successful operation of the Communify gem, please include the following gems in your application's Gemfile:

gem 'sidekiq'
gem 'redis'
gem 'dotenv-rails'

Make sure to have Sidekiq running in the background. To start it locally, execute:

bundle exec sidekiq

Usage

To set up logging for notifications, run the following command in your terminal:

rails g communify:install

This command will generate a migration file and a model named CommunifyLog. Next, execute:

rails db:migrate

This creates a database table with the following fields:

• title: The title of the push notification.

• content: The message or notification text to be sent.

• recipient: The recipient's mobile number for SMS or the registration ID (generated when the app is installed) for push notifications.

• priority: An enum with options:

  • urgent (0 minutes)
  • high (5 minutes)
  • medium (30 minutes)
  • low (60 minutes) Messages with urgent priority trigger the Sidekiq job immediately, while high priority messages are triggered in 5 minutes, and so on. The default value is urgent.

• content_type: Indicates whether the log is for SMS (0) or push notification (1).

• status: Stores the status of the message/notification, indicating whether it was successfully sent or failed (including error details).

• third_party_id: The ID generated when a message or notification is successfully sent.

• attempt_count: Automatically generated, indicating the number of attempts made to send the message. Messages are attempted a maximum of three times.

Maintaining logs provides a comprehensive record of all messages and notifications sent, enabling effective tracking and troubleshooting. This aids in identifying delivery issues, enhances user engagement analytics, and ensures compliance with regulatory requirements, ultimately improving communication reliability and efficiency.

Sending SMS

To configure Twilio keys in your application, run the following command:

rails g communify:sms

This command creates a communify_sms.rb file in the config/initializers folder. Uncomment the relevant lines and set your account_sid, auth_token, and sender_no with the keys from your Twilio account.

To send an SMS, add the following line in your controller method:

Communify::Controllers::Sms.send_message(content, recipient, priority) # Returns the resource_id if successful

• Content: The text message to be sent.
• Recipient: The recipient's number, including the country code (e.g., “[phone]”).
• Priority: Choose from “urgent,” “high,” “medium,” or “low.”

Sample Log:

<CommunifyLog id: 1, title: "", content: "OTP from abc app: 123456", recipient: "[phone]", attempt_count: 1, status: "Message Delivered at 2022-12-12T15:20:45+00:00", third_party_id: "SMaf7c76052f9c5180c03abc5c73d67d9", created_at: "2022-12-12 15:20:45", updated_at: "2022-12-12 15:20:45", priority: "urgent", content_type: "sms">

Sending Push notifications

To configure device information, run the following command:

rails g communify:push_notification

This command generates a migration file, a model and fcmpush.rb in the initializers of your project folder. After that, execute:

rails db:migrate

This creates a table named Devices with the following fields:

• device_id: Registration ID for the device.

• device_name: Name of the device (e.g., Android/iOS/Web).

• person_id, person_type: User ID and class name associated with the device

Get the registration ID/device ID (generated by the FCM SDK for each client app instance) from the frontend, link it with a user and store it in the Devices table using:

Device.create(device_id: "registration_id goes here", device_name: "Name of the device", person: user)

Sending Notifications

1. Generate Service Account Key:

   • In the Firebase Console, go to Project Settings > Service Accounts
   • Click on Generate New Private Key and download the JSON file. Store this JSON file securely.
   • Be sure to add the private key file to your .gitignore.

2. Store FCM Project ID:

   • In the Firebase Console, navigate to your project.
   • Go to Project Settings > General to obtain your FCM Project ID.
   • Store the value in your environment variable with the name FCM_PROJECT_ID to use it with Communify.

3. Configure Initializer:

   • Add the path to the JSON key file in the initializer generated previously under config.json_key_io.

4. Send Notification:

   • Add the following line of code in your controller to send a notification:

Communify::Controllers::PushNotification.send_push_notification(title, content, recipient, notification_type, other_details, priority)

• Title: The title of the notification.
• Content: The text of the notification.
• Recipient: An array of registration IDs (e.g., ["reg_id1", "reg_id2"]).
• Notification Type: A keyword to inform the frontend where to redirect the user when the notification is clicked.
• Other Details: Additional information sent to the frontend that is not visible to the user (can be a string or JSON converted to string).
• Priority: Choose from "urgent", "high", "medium" or "low".

Note: In this context, registration_id and device_id are used interchangeably.

Sample log:

<CommunifyLog id: 1, title: "Notification title", content: "Notification content", recipient: "["e2x7BuarRx2tHqv7p80LBJ:APA91bEsh1_ouyuwLvtt06UCX...", attempt_count: 1, status: "Notification Delivered at 2022-11-08T07:17:57+00:0...", third_party_id: "0:1667891877225583%d8a4a6c1d8a4a6c1", created_at: "2022-11-04 14:28:27", updated_at: "2022-11-04 14:28:27", priority: "urgent", content_type: "push_notification">

Maintaining Email logs

To enable logging of all emails sent through your application, run the following command:

rails g communify:email

This command generates a mail_observer.rb file in the config/initializers directory. Observers provide access to the email message after it has been sent, allowing you to maintain logs in the CommunifyLog table.

The logs will include essential information such as the content, recipient email address, and timestamps of when the emails were sent.

Sample log:

<CommunifyLog id: 1, title: "", content: "Subject: Verify your email address, Body: <...", recipient: "[e-mail]", attempt_count: 1, status: "Mail delivered at 2022-12-12T14:47:44+00:00", third_party_id: "63973f107deb7_d32c53f9f6e105da41323d@ip-172-31-10-...", created_at: "2022-12-12 14:47:45", updated_at: "2022-12-12 14:47:45", priority: "urgent", content_type: "email">

This logging functionality enhances your application's communication audit trail, making it easier to track email interactions with users.

Contact & Support

If you have any questions, suggestions for enhancements, or encounter any issues while using Communify, please feel free to reach out. We're here to help you maximize your experience with our gem!