RP Samara > Support Documentation


FAQ

Where does the name Samara come from?

I just mainly wanted to distinguish my (third-party) app from anything really official from RingPlus. Also, the RingPlus website has its own Dashboard, so there was confusion (at least to my mind) when people mention something about website features vs. features in the app. As for the particular Samara name... just something random.

Is it one subscription fee per google account?

If you buy the premium upgrade, you have full premium forever, on whatever RP account you want. The premium license is tied to your Google Play account, so you can install the app on as many phones/devices as you wish and still get premium. Plus, it's not a subscription. It's a one-time purchase for premium for life.

Does the API give you info such as the account's data limit for the month? Assuming the debug data is all you get to work with, then sadly no. A few new API calls could make your job (err, I mean hobby) a lot easier!

Amen, brother!! Your assumption is correct: no allotment info at all from the API. That's why supporting plans is so difficult and error-prone. I have to manage plan details myself. That's also the reason I built out the Configure Plan functionality, so that users can specify their own allotments. It's almost impossible keeping up with constantly evolving plan lineup, so it's best to let users adjust some of those details. RingPlus, if you're listening, please add plan info (allotment amounts) to the API. That would be incredibly awesome and make everything soooo much easier!

Let's hear it from the horse's mouth: @hungryghost: do you get complaints from customers that your app does not reflect their true usage? And if so, how many of your subscribers report that and what's your typical response to them?

I checked with the horse. He recalls only a few people ever inquiring about discrepancies between app and website. Two of those people appear to be named @1birdman1 and @jongasse. There may have been a couple more, but those are the two that come to mind. Very few people inquire or bring up these kinds of questions (not that I mind at all).

But, let's be clear about something. The discrepancies the horse is talking about is related to History information. Sometimes, there are instances of call durations being misreported by the API. But this only affects the History screen, when looking at individual calls. Sometimes, a call will be listed as shorter or longer (in duration) than it actually was. This issue is a longstanding (known) bug in the API. It only affects the History screen though. It does not affect Current Usage numbers on the main screen. The usage numbers on the main screen are solid.

Where do you find MMS usage? Shouldn't that be listed alongside voice, SMS, and data?

As you've discovered, clicking the icon above the usage "ring" will toggle between SMS and MMS. You can also long-press the icon if you want to make it the default display (e.g. to always show WiFi or MMS when the app is started).

just figured out how to delete alerts, swipe from left to right or right to left through the alert name!

Yes, that's how to delete an alert, by swiping left or right. I probably need to change something in the app to make this more obvious.

Is it possible to purchase plan add-ons from Samara?

Sorry, this isn't possible. The API simply doesn't support billing transactions like this. The website is really the only way to manage add-ons. I've included a "top-up" link in the Samara app that makes launching the website a bit easier. You can use that same "top-up" link then just navigate to the add-on page in your browser. That's about as good as I can do in the app, unless RP changes the API.

have you considered adding a widget

Widgets are a popular request, and again, something I'm considering for a future version. It may be more in the form of persistent notifications (in the pull down notification tray) rather than typical widgets though, simply for ease of implementation.

Can you explain the reason for the permission to access Contacts?

Sure. I addressed this elsewhere, but I've since removed most of the extraneous permissions the app wasn't using.

The app still asks for the 'Contacts' permission though. This is for thumbnail photos, so that you'll have a nice little contact image to look at for each phone number. Contact thumbnails only work if you actually have a photo assigned to that particular phone number (in your contacts or address book). If not, the app just displays a generic contact avatar (with variations in color). That's it. Nothing nefarious going on here (except the NSA backdoor I slipped in, but I wasn't supposed to mention that.)

Is it possible to add multiple accounts (say one line per account), or will it only display multiple lines on a single account? I can't find a way to sign in on a second account.

The app only supports a single RingPlus user id (login email). If you want to use another user id, you have to reset the app by going to Settings > Reset App. If you do that though, you will lose all your previous data and will have to authorize the app again (under the new user).

That's really the only way to use multiple user ids with a single app install. You can, though, install the app on multiple devices and log in with different user ids on each device. There's no limitation on number of devices. If you buy premium, the upgrade will be good for all your app installations (associated with your Google Play Store account).

I have 3 diff phone numbers on 3 diff R+ accounts. If I buy the Premium, can I install it on 3 diff phones?

Yes. Your "premium" is tied to your Google Play Store account, so as long as you use the same Google account on all 3 phones, premium will work on all of them.

Can Samara block usage after it reaches a limit?

The app can't do any blocking, only alerts. So you have to manually go to the website to turn off minutes, text, data, etc. Sorry, there's no other way to do it unless RingPlus changes their system to allow third-party apps to update those settings.

Can you please add move to sd card feature to rp samara? Phone has low application storage.

The app already is pretty small though. It only takes maybe 10-15 MB of file space, depending on the number of phone lines you have. The apk itself is under 3 MB, but this gets inflated post-install and grows along with your downloaded data. The app never usually goes over 15 MB or so (in my testing), but this will vary depending on how much offline history you save. I can't imagine it'll ever go above 20 MB though.

Anyway, I can certainly do things to improve file system efficiency (like offloading to SD Card or improved cache handling). I'll look into it if time permits. But if you're tightly space-constrained on a particular device, changes to the RP Samara probably won't have much noticeable impact.

[Magic Rewards Add-on] had been visible on the previous version of the app and showed the available Magic referral bonus.

The magic referral amounts only show up when actual magic usage has occurred. There's actually no way to report the available magic amounts. Only after magic amounts have been used, the app will report those magic usage numbers. When there is no usage detected for a given day, that magic section won't appear at all. This usage-only reporting of magic amounts is, unfortunately, a limitation of the current RingPlus API. Sorry, but that's just how it works.

So, basically, if you don't see any magic amounts for a given account, that's because there wasn't any magic amounts earned and used that day.

I wish I could find a way to access two accounts with the app. I have 2 phones on separate accounts. But the app will only allow me to access one account. Unless I can merge the accounts together it's my only option to keep two separate accounts. Any suggestions?

Multiple RingPlus logins is not supported by the app. You can, though, install RP Samara on multiple devices and use a separate login for each device. The only way to switch the login on an existing Samara installation is to go to Settings and do Reset App. That will clear out all the data and start fresh (prompt you to login and authenticate again).


HELP ARTICLES

Privacy Concerns

All RingPlus data the app downloads remain on your device. Your information is never transmitted or collected outside of your device, except for these two cases:

  • Debug information - If you manually submit your debug information, your RingPlus data will be emailed to me for troubleshooting. The debug info is stripped of sensitive information (like voicemail PIN, or phone number, etc.), so there shouldn't be privacy concerns with what's sent in. If you want to see exactly what's emailed in, just check your Sent mail folder.
  • Plan names - The name of your current RingPlus plan is submitted to my servers when the app is determining your plan allotments (only once per plan cycle). This plan name submission is anonymous (only the literal plan name is sent in) and aggregated with other users. This is how I've been able to keep up with the march of new plans lately. The plan identification process is partially crowd-sourced.

That's it. No other information is collected. I can't say it'll remain this way forever. There is a chance the app will begin collecting more info in some future release. Certain feature requests would necessitate more data collection, such as password protecting individual phone numbers, or any other cloud-based functionality. For now though, there's nothing like that in the app. But if I ever do add something like that in, I'll make it explicitly clear what the app is doing.


A Note About Sign-In

Also, Let me explain a bit about the app sign-in process. The app never sees or stores your RingPlus username or password. When you authenticate the app, you are sent to the RingPlus website for sign-in (not my servers). This is by design and it's based on how RingPlus has set up an OAUTH-based API. You basically sign into RingPlus to let their servers know that you want XYZ app to access your data. Once XYZ app is granted permission by RP servers to do so, it all works. But the app never has access to your username or password, and you always have the ability to revoke access from the RingPlus website. This is the beauty of OAUTH and apps that use it. It helps keep everything more secure for those with privacy concerns. And if you ever have doubts, you can easily revoke access.


Information Security and RingPlus OAuth

RP uses non-expiring refresh tokens. This is fairly common in the oauth world, but it is also common to see oauth implementations where tokens expire after say 1 week or a month. It's really up to the auth provider to decide whether to expire tokens or not. In RP's case, they went with the less-sensitive info-sec model and decided to allow "permanent" auth tokens (similar to Facebook and other large companies who, arguably, control even more personal info than RP). But if an app developer decides to override the default oauth lease and require re-login, that's perfectly fine.

My take on RP's oauth implementation is that I was initially concerned about security of private/personal account info. The most sensitive data probably is someone's call and text history. But here's the thing, leaving a RP app "permanently" logged in is essentially the same as signing into the RP Dashboard website (without explicitly signing out, which is the norm use case). The RP website (either via phone or computer) persists logins between sessions by default, so private RP info will be viewable by anyone who has access the browser. Even more importantly, a person's call and text history is also available through various unsecured sources, like a phone's dialer app or a phone's text messaging app. These ("stock") apps require no authentication, so the history info there is already far less secure than the history info in any RP oauth-based app. So, ultimately, if someone really wants to secure their communications history, they need to address physical device security. Basically, everyone should use lock screens and strong passwords, if at all concerned about privacy (which they should be).

As for application-level security, some apps and websites deal with sensitive enough info to warrant per-session authentication (or re-auth after X number of sessions). In these cases, it's definitely up to the developer to implement this extra layer of security. This is especially important for financial transactions, medical records, etc., but, in my opinion, not so much for RingPlus data. If someone is really concerned about hiding their RP account activity, they should logout after each session. Although the RP API doesn't provide a method for apps to expire tokens, a developer can effectively force a "logout" by simply discarding any stored tokens. But, once again, this still leaves communication history info easily accessible via other apps on the phone, so an RP app logout won't actually accomplish much in terms of info-sec.

Basically, what I've described is the thinking behind the information security model I use in RP Samara. I'm not saying my approach is the only approach, but I have indeed thought a lot about these RP API security issues and this is ultimately what I felt comfortable with.


App Permissions

In-app purchases

  • For purchasing upgrades, etc inside the app.

Identity

  • find accounts on the device
    • Not exactly sure. Probably related to in-app purchases (to make sure purchases are applied to the correct Google account). App doesn't explicitly request this permission, so it must come from one of the Google services the app uses.

Contacts

  • read your contacts
    • For displaying thumbnail photos for phone numbers.

Location

  • approximate location (network-based)
    • For retrieving cellular/telephony information for the device (if applicable). Related to some compatibility checking done on app launch.

Photos/Media/Files

  • modify or delete the contents of your USB storage
  • read the contents of your USB storage
    • For reading and writing data to device. All downloaded data is locally cached.

Device ID & call information

  • read phone status and identity
    • For retrieving device/phone info so app knows which phone it's installed on (if applicable). Only relevant on initial setup when RingPlus login contains multiple phone numbers.

Other

  • receive data from Internet
    • For downloading RingPlus and user/app data.
  • control vibration
    • For app notifications (e.g. Usage Alerts).
  • full network access
    • For downloading RingPlus and user/app data from internet.
  • view network connections
    • For detecting and controlling app data usages for WiFi and mobile.
  • run at startup
    • For scheduling background syncs (related to Usage Alerts).
  • prevent device from sleeping
    • For keeping background process alive so RingPlus API async can finish.
  • use accounts on the device
    • For accessing content providers (related to sync accounts).

How To: Usage alerts

The purpose of Usage Alerts is so that you don't have to manually monitor usage throughout the day. Instead of launching the app or pulling up the website, you can simply create Samara alerts that will notify you when you surpass a pre-defined usage amount.

How it works:

  • Usage alerts run on a schedule, based on the frequency listed under Settings > 'Check usage' ["Every few hours", "Twice a day", "Once a day", or "Never (alerts disabled)"].
  • When it's time to check usage, the app gets your current usage info from the RingPlus servers.
  • If an alert is triggered (for example, Balance is under $5), the app issues a notification.
  • Once a notification is created, the alert becomes dormant for the rest of the billing period (e.g. "Balance under $5" won't trigger again until the next month).
  • If you want additional notification levels, it's possible to create layered alerts (premium feature). For example, you can set a series of low balance alerts for $5, $3, and $1 or create several data usage alerts for 200MB, 250MB, 300MB, and so on.

Usage alerts are not foolproof

There are reporting delays, both in-between 'Check usage' cycles and from the time of actual usage to when usage is reported by the Sprint network. Due to these delays in accounting for usage, you should set your Usage Alert thresholds with additional "padding" or "slack". For example, if you're worried about going over 500MB, be cautious and set your alert to something like 400MB.

Even when using conservative usage alert triggers, there is no guarantee that you'll be notified before large jumps in usage. Depending on how you use your device(s), it's possible to consume large amounts of minutes, texts, or megabytes in a relatively short period of time.

Preventing usage

Alerts only notify you after usage has occurred. Usage alerts do not prevent excessive or runaway usage. Alerts are not a replacement for responsible habits. If you want to actually prevent things like excessive data usage, you can set "hard caps" on your device. For Android, I recommend using the built-in system's data cap feature (usually found under System Settings > Data Usage > 'Set cellular data limit'). For other services, like talk or messaging, I recommend using common sense. You can also use tools like RingPlus Service Timers (found on the RingPlus website dashboard) to restrict service on a particular device (for, say, a text-obsessed family member) to certain times of the day.


How To: Speed up your Android 4.4 (e.g. LG Volt)

For people using Volts or other devices on Android 4.4 (KitKat), here's a suggestion to give your device a performance boost. Try configuring your system to use the ART runtime environment instead of the default Dalvik.

Instructions: How to switch to ART runtime.41

Warning: Although ART is mature and stable, there's a chance some apps will have issues if you switch. The ART runtime was introduced in Android 4.4 as an optional runtime (an alternative to the older Dalvik). In Android 5.0, ART completely replaced Dalvik. So, it's been a couple years already, but it's still possible that some older apps will have glitches.

With that said, almost all apps are fine with ART, and in fact run noticeably better than with Dalvik. You'll get good performance boost simply by switching. For example, the RP Samara app is far less sluggish on a Volt running ART compared to the default Dalvik. Most of your apps should similarly benefit from ART's more efficient runtime.


How To: Submit debug info

I've notice a few Google crash reports trickling in. Thanks to anyone submitting those. If you want these kinds of things fixed, that's how you do it! That info is very useful when trying to track bugs down.

If you encounter issues like this, please also let me know via my contact page or simply send in your app debug info by doing the following:

  • Enable Settings --> "Allow debugging"
  • On the main screen, long-press on plan name
  • "Debug Information" window will open.
  • Tap on "Email" to submit your info

The email is sent through your regular email app, so just write a short note at the top of the email to let me know what happened (e.g. "app crashed").


How To: Manually configure a plan

It has come to my attention that people may be unaware of how to manually configure a plan in the app.

If you are on a recent RingPlus plan and the plan allotments are not appearing correctly in the app, you can easily configure the plan details by doing the following:

  • On the main screen, click on the icon (either a wrench or exclamation point) next to the plan name
  • On the next Configure Plan screen, manually enter your plan allotment amounts
  • Manually enter the overage rates (usually 2¢ for everything except Int'l SMS 3¢ and MMS 4¢)
  • Click 'Save'
  • The main screen usage "rings" should now display the correct amounts. If not, close and restart the app.

If new plans don't show up after updating to v2.2...

Here are a few things to try:

  • Go to Configure Plan screen by clicking the icon next to plan name (either wrench or exclamation icon)
  • Click the Reset plan button
  • If plan still doesn't show up correctly, close the app (completely) then restart.
  • If still no go, then the final thing to try is to go to Settings and do a complete Reset (this deletes all previous data though and requires reauthorization).

If none of the above resolves plan issues, please let me know. Thanks.


How To: Change order of phone numbers

  • Open up the navigation menu (icon in the upper-left)
  • Click on the name/phone number area in the header
  • In the list of all numbers, long-press on any item then drag it around to re-order the list

Version History

RP Samara v2.3

This is a minor update primarily focussed on bug fixes and stability improvements.

Main changes in version 2.3:

  • Minor graphical UI updates
  • Added support for fractional overage rates
  • Fixes for crashes under certain conditions
  • Fixes for various stability issues
  • Fix for SSL security issue
  • Various other bug fixes

RP Samara v2.2

This is mostly a maintenance update with the primary focus being support for the latest plans, add-ons, and promos.

Main changes in version 2.2:

  • Support for all plans (as of today), including proper support for unlimited in-network (RP-to-RP) minutes and text plans.
  • Fix for Data Alerts, which were reporting bytes instead of megabytes.
  • Fix for crash in History, when clicking on certain items.
  • Fix for crash in Settings, when opening on certain devices.
  • Stability fixes and other minor bug fixes.
  • Various minor UI changes and graphical tweaks
  • (re)Added app permission for external storage. This permission was removed in v2.1, but ended up causing the app to sometimes crash. This permission is required for ringtone preferences on some devices that have SD cards.

RP Samara v2.1

Main changes in version 2.1:

  • Reduced app permissions
  • New add-ons and promo packages
  • New hide inactive accounts feature (in Settings)
  • New forecast with add-ons feature
  • Bug fix for no account info (555-555-5555) after relaunch
  • Other minor bug fixes
  • Various UI updates

Some things to note about this version:

That annoying 555-555-5555 bug is fixed
This only affected those with limited-RAM devices (hello, Volt), but apparently, that's most of you! Sorry about that. I've put Samara through some memory training, and she's good now.

All RingPlus plans are now supported
The plan system (in the app) has been completely redone. Plan allotments and other details now should be much more accurate. When a new RingPlus plan is released, the app should refresh automatically without requiring any new app download. One thing to note: if you do encounter incorrect or missing plan information, and it's been longer than a couple days, please either post about it here or contact me directly through my contact page.

Add-ons and promos
These are now displayed on the main screen below the regular plan usage info. Add-on info includes usage amounts and expirations times. You can also tap on an item to reveal the add-on name.

The Forecast screen has been refreshed
It's the first real update to this feature in a long time. Now there is a toggle option to compare forecasts with and without add-ons. Another cool trick (which I might build out in a future release), is if you want to compare forecasts between different plans. To do this, you can go to Configure Plan, select another plan, then go back to Forecast to see how the forecast has changed.

Hide inactive accounts
You can now hide inactive accounts (through Settings). If you ever want to see them again (say, if your account gets suspended), you can always go back to Settings to view them again.

Debugging option
For those who like to look under the hood, please note that tapping 10-times on the details box no longer pops open the debug window. To view the debug info, you have to long-press on plan name (assuming you have debugging enabled in Settings).


RP Samara v2.0 (formerly R+Dashboard app)

The app is now called RP Samara (no longer R+Dashboard). I changed this in order to avoid confusion with the RingPlus website dashboard. This new version has also undergone a complete redesign of the UI and navigation, and it's also picked up a number of new screens and features.

Main changes in version 2.0, in no particular order:

The latest RingPlus plans are now supported
I was only able to test a handful of them, but all plans should work much better, since plans are now configurable within the app when there's wrong/missing plan details.

RP Samara no longer displays ads
None at all, for free or premium users alike.

No more 30-day free trials
I've decided to get rid of trials periods in order to reduce complexity, and also because:

Free users now have permanent access to History and Usage Alerts!
But with restrictions and limitations. It's not as good as full premium, but it's still good and it's free!

History has gained new "actions"
You can now start a call, text message, or block a number (links to RP call filters) right from History.

Usage Alerts for multi-accounts
You can now create usage alerts for all accounts/numbers under a user id, not just the "default".

Usage Alerts are now highly configurable
You can have multiple levels of alerts in any combination that you want.

Premium upgrades purchased in-app are no longer tied to user ids
So if you buy it once, you can use the premium upgrade across as many RingPlus logins are you want. The upgrade is only tied to your Google Play account.

Subscription are no longer available
The only premium upgrade option is now a one-time in-app purchase. No more ongoing subscriptions.

New "Cross-grade" option
For people who want to switch from an existing subscription to a full premium license, this can be done by purchasing this crossgrade. It's only $.99.

The Samara Launch Promotion
Until the end of August, the full premium license is only $1.49. So, get it while it's hot!

Some known issues:

Installation failures on some older Android phones.
This is the reason I was up all night. I couldn't resolve it, so just had to go ahead and publish it as-is. Luckily, this should only affect a very small number of users, those still using ancient phones with Android 2.2 or 2.3. I'm tempted to just drop support altogether on these old platforms since supporting them is so difficult.... but for now, I'm still trying my best to fix these issues.

Add-ons are not supported
I'm currently not too sure how to manage these. So for now, they're simply not supported.


R+Dashboard v1.3

Main changes in version 1.3:

  • Multi-Accounts - Free users of the app (non-premium) can now access multiple accounts (just like premium users)
  • Low Balance Alerts - Notifies you when your account balance goes below a minimum amount
  • Data Usage History - Data history can be viewed as daily summaries instead of as individual usage sessions. This should cut down on the sometimes hundreds or thousands of history records, and make it easier to track your actual data consumption. Now, you can clearly see how much you used on a given day.
  • Top Up Balance - There is now a link that will forward you directly to your account's Top Up page on the website. There's currently no way for the app to handle top ups directly, but this should make it easier to top up when you're running low.
  • Graphical Changes - Minor modifications to the Main screen look and feel to (hopefully) make things clearer/more intuitive.
  • Bug fixes - A number of bug fixes in this release, including a workaround for the SSL problem on certain phones that prevents app authorization/sign-in (showing a blank screen instead of the Ring Plus login page).

R+Dashboard v1.2

Main changes in version 1.2:

Usage History [NEW]
The Usage History feature allows you to download Ring Plus history data for offline browsing and analysis. Once downloaded, the information is saved to your Android device and no further downloading is required (except for new history). The app automatically sorts history into the different categories (Minutes, SMS, MMS, Data) and usage is grouped and summarized per billing cycle. The app calculates each month's usage and costs to help you manage your spending patterns.

Usage Forecasts [NEW]
The Usage Forecast feature takes your most recent usage information and makes predictions about your monthly totals. With this forecasting tool, you can better plan how to use your mobile service while staying on top of overage costs.

Some known issues:

  • Forecasts Screen may show "invalid" for the date in some cases. This occurs if the app hasn't been refreshed (no network connection?) since the last billing cycle. If you encounter this, just manually do a 'Refresh' on the main screen and open Forecasts again.
  • Usage Details (the panel on the Main Screen that opens below the bar chart) sometimes shows incorrect "Est. Cost" for voice minutes. This issue also exists in previous versions of the app and also affects the new Forecasts screen. The cost estimate may be incorrect if you've made international or other types of toll calls. Intl and/or toll calls are not reflected in costs estimates because the estimates only cover overages (at least for now). Until this changes, please use the History screen to get your actual billed costs for voice minutes (not just estimates).
  • Minutes shown on the History Calls tab sometimes don't match the Ring Plus website. This is a problem with how the server sometimes reports call durations. There are some discrepancies with how calls (not texts or data, only calls) are reported, which could lead to an under/over reporting of minutes on the History screen (the call costs will be correct though). If you see a discrepancy, always trust the website over the app. You can also check your total minutes on the main screen, because totals displayed there are reported differently by Ring Plus and seem to be the most reliable.