SDK Quick Start Guide
Table of Contents Requirements...3 Project Setup...3 Using the Low Level API...9 SCCoreFacade...9 SCEventListenerFacade...10 Examples...10 Call functionality...10 Messaging functionality...10 Rich Messaging functionality:...10 UI Control...10 IStartControl...10 Controllers, ViewDescriptions and ViewHolders...11 Customization...12 Overriding Resources...12 Subclassing Controllers...12 Database Access...13 2
Requirements C2Call SDK Android SDK Eclipse IDE Android Development Tools (ADT) plugin for Eclipse IDE Project Setup 1. Unzip C2Call- SDK_Android_Vx.x.zip (contains library project lib- c2callsdkres) 2. Import library project lib- c2callsdkres into Eclipse workspace: 1. Menu File Import 2. Select: General Existing Projects into Workspace 3. Next Select root directory: Browse to unzipped C2Call- SDK and select Project lib- c2callsdkres Finsh 3
4. Clean/Build the library project imported in previous step. 5. Finsh. 3. Create new Android Project: 1. File New Android Application Project 2. Enter Application- /Project- /Package name at will 3. Set Minimum Requirered SDK to API 12 and Target SDK to API 17 4. Click through the rest of the wizard at will depending on how the app should look like. 4. Add the following line to the file <Project Root>/project.properties manifestmerger.enabled=true 5. The SDK bundles the library android- support- v4.jar. If your app links against that library by itself then you have to delete that library from your libs folder in order to avoid library version conflicts: 4
6. Link your app to the SDK project: 1. Right click your Project Properties Android 2. In Library (bottom right) click Add and select 5
3. lib- c2callsdkres 7. Copy the file res/values/c2call_config.xml to your app's res/values folder and fill in the keys in order to use features that need Goolge Maps or Google Cloud Messaging (GCM) 8. Add the following provider definition to your AndroidManifest's application tag <application...>... <provider android:name="com.c2call.sdk.lib.db.provider.c2callcontentprovider" android:authorities="<your package name>.content" android:exported="true" android:granturipermissions="true" > <grant-uri-permission android:pathpattern=".*" /> </provider> </application> 6
and replace <your package name> with the package name of your app. E.g. if your package name is com.mypackage then the authorities of your provider would be: android:authorities="com.mypackage.content" Note: You may get an error about the exported=true attribute. If that is the case, then you have to disable that error (or set its severity to Warning ) within the Lint settings: 9. You have to create an Application class and initialize the SDK in its oncreate() method. The class should look similar to this: package com.c2call.demo; import com.c2call.sdk.pub.affiliate.affiliatecredentials; import com.c2call.sdk.pub.core.c2callsdk; import android.app.application; public class DemoApp extends Application { @Override public void oncreate() { //You get these values when creating an app in the C2Call developer area 7
} } //https://www.c2call.com/developer-area.html String affiliateid = "<your affiliate id>"; String secret = "<your secret>"; final AffiliateCredentials credentials = new AffiliateCredentials(affiliateId, getpackagename(), secret); C2CallSdk.instance().init(getApplicationContext(), getpackagename(), credentials); super.oncreate(); 10. Assign your Application class created in previous step in your AndroidManifest's <application> tag. In the example above it would be: <application android:name="com.c2call.demo.demoapp" android:allowbackup="true" android:icon="@drawable/ic_launcher"... 11. Register the GCM Receiver (see: GoogleCloudMessaging for more details) <receiver android:name="com.c2call.sdk.pup.broadcast.gcmbroadcastreceiver" android:permission="com.google.android.c2dm.permission.send" > <intent-filter> <action android:name="com.google.android.c2dm.intent.receive" /> <action android:name="com.google.android.c2dm.intent.registration" /> <category android:name=<your Package Name> /> </intent-filter> </receiver> 12. A complete minimal AndroidManifest may look like this: <?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.c2call.sdkdemo" android:versioncode="1" android:versionname="1.0" > <uses-sdk android:minsdkversion="12" android:targetsdkversion="17" /> <application android:name="com.c2call.demo.demoapp" android:icon="@drawable/ic_launcher" android:label="@string/app_name"> 8
<activity android:name="com.c2call.sdkdemo.mainactivity" android:label="@string/app_name" > <intent-filter> <action android:name="android.intent.action.main" /> <category android:name="android.intent.category.launcher" /> </intent-filter> </activity> <provider android:name="com.c2call.sdk.pub.db.provider.c2callcontentprovider" android:authorities="com.c2call.sdkdemo.content" android:exported="true" android:granturipermissions="true" > <grant-uri-permission android:pathpattern=".*" /> </provider> <receiver android:name="com.c2call.sdk.pup.broadcast.gcmbroadcastreceiver" android:permission="com.google.android.c2dm.permission.send" > <intent-filter> <action android:name="com.google.android.c2dm.intent.receive" /> <action android:name="com.google.android.c2dm.intent.registration" /> <category android:name= "com.c2call.demo /> </intent-filter> </receiver> </application> </manifest> 13. Now you are ready to go. Using the Low Level API SCCoreFacade The class com.c2call.sdk.pub.facade.sccorefacade provides a convenient way for a low- level access to major C2Call communication features: Phone calls to PSTN and mobile phone networks VoIP and video calls Group calls (VoIP and Video) Instant Messaging SMS / Text Messages Rich Media Messages like phone, video, location, etc. This class also provides the core functionality to start and stop the C2Call service and handles the background behavior. 9
SCEventListenerFacade The class com.c2call.sdk.pub.facade.sceventlistenerfacade is used to receive basic status events from the SDK. E.g.: Online status change Incoming call Call status (connected, rejected, hungup...) Error events Examples Call functionality // Call the C2Call TestCall SCCoreFacade.instance().call( 9bc2858f1194dc1c107, false, false); Messaging functionality // Send an SMS / Text message SCCoreFacade.instance().sendMessage( +1408234123456", Hi, this is an SMS"); Rich Messaging functionality: // Send an image String filepath = getfilepath(); SCCoreFacade.instance().sendImageMessage( max@gmail.com", Hi, see my photo", filepath); UI Control IStartControl The C2Call SDK comes with a rich collection of UI elements that provide access to the various C2Call SDK Features. 10
The central class that manages everything within the SDK is C2CallSDK. Beside other things, this singleton holds an implementation of IStartControl which in return provides convenient methods to start and control most GUI elements of the C2Call SDK. For example to open a Dialpad in a new Activity you only have to call: C2CallSDK.startControl().openDialpad(context, null, R.layout.sc_dialpad, StartType.FragmentActivity); Of course, you can sub- class IStartControl and provide your own handling. Controllers, ViewDescriptions and ViewHolders While the default implementation of IStartControl (SCStartControl) works out of the box and may be sufficient in many cases and up to a certain level of customization, you will have to derive that class in order to use custom views and/or controllers. The basic concept is that every view (in most cases a res/layout file) is described in a so called ViewDecsription. This ViewDescription maps the IDs of the view's elements to defined functions of the C2Call SDK. For example: You create a layout file my_dialpad.xml, wich in return has a button with anroid:id= @+id/btn_call. Now, if you want to connect that button with the Controller's call functionality, then you have to specify a mapping between those; in this example it would be something like ViewDescription vd = new ViewDescription(new int[] {SCDialpadViewHolder.VD_BUTTON_CALL, 0, R.id.btn_call}); Of course, a single ViewDescription can hold many of these mappings, i.e. you will map every standard button of the dialpad in such a way. The so called ViewHolder now takes such a ViewDescription as well as an inflated instance of your layout file (or otherwise created View) and create references to the elements mapped in the ViewDescription. 11
The last part in this chain is the Controller, wich binds needed listeners and controls the behavior of the elements within the ViewHolder. E.g. The DialpadController checks if the ViewHolder contains a button that was mapped to the call functionality; if that is true, then it will bind an OnClickListener to that button which will handle the call when clicked. There are element- specific Controller- and ViewHolder interfaces for every standard GUI element (within the C2Call SDK) as well as default implementations of those that work out of the box. Similar is true for ViewDescriptions: Layout files and fitting ViewDescriptions are available for all elements. Customization The C2Call SDK provides several ways and levels of customization. But in the end it boils down to two major concepts. Overriding resources and subclassing Controllers. Overriding Resources The Android build system allows the overriding of resources of library projects. This makes it very easy to customize the look and feel of your app without touching a single line of Java code. For example, to change the background of the call button of the dial pad you would simply put a file called sc_dialpad_btn_call.xml in your res/drawable folder. This will override the corresponding file in the library in the button's background is changed. Most items use a style which is defined in res/values/c2call_style.xml, this may also be overridden. The same is true for all other resoucres like strings, colors, dimens and whole layouts. So if you want to write a new dialpad layout from scratch with its very own look and feel then you are free to do so. You only have to make sure that the layout and all items are named like the original ones. E.g. The layout has to be named sc_dialpad.xml and the call button sc_dialpad_btn_call and so on. Subclassing Controllers While overriding resources is a simple and quite non- intrusive way to change the look and feel of your app this may be not enough for your purpose. For example if you want to add some extra functionality to the call button of the dialpad (like fire tracking events or whatever), you will have to subclass the specific controller as well as the surrounding Fragment/Activity. For instance to override the call button event in aboves example you will have to create a new Activity like: and then override the oncreatefragment() method like: public class MyDialpadActivity extends SCDialpadFragment Activity { //... } 12
public class MyDialpadActivity extends SCDialpadFragment Activity { @Override protected Fragment oncreatefragment(){ return new SCDialpadFragment(){ @Override protected IDialpadController oncreatecontroller(view v, ViewDescription vd){ return new SCDialpadController(v, vd){ @Override public void oncallclick(view v){ //Do something } } } }; } }; super.oncallclick(v); Database Access The C2Call SDK uses Android's standard implementation of SQLite to store most of its data (like friends, phone numbers, messages, etc) and OrmLite to map these data to Java objects. The database schema is defined by the data classes and its annotations. You find these data classes in the package com.c2call.sdk.pub.db.data: SCBaseData SCBoardEventData SCBoardEventExtraData SCDirtyFriendData SCFavoriteData SCFriendData SCFriendExtraData SCGroupInfoData SCMediaData SCMissedCallData SCOpenIdData SCPhoneData 13
You can get Dao to any of these classes through the singleton com.c2call.sdk.pub.db.util.core.databasehelper. Example: Dao<FriendData, String> dao = DatabaseHelper.getDefaultDao(SCFriendData.class); With this Dao you can read from and write to the specific table. Please read through the docs of OrmLite, there are plenty of tutorials and examples. Please visit our forum for support or any feedback. 14